Improving docs

README.md

@@ -12,27 +12,53 @@ Provides a Python library, command line tools, and pre-commit tools to manage co
 
 ## Command line
 
-From the command line:
+### conda_envfile_merge
+
+Merge different environment files.
+For example:
 
 ```bash
 conda_envfile_merge -a "extra-library" env1.yml env2.yml > env3.yml
 ```
 
 merges `env1.yml` and `env2.yml` and adds the package `extra-library` to the merged environment file `env3.yml`.
 
+### conda_envfile_diff
+
+Show the difference between two environment files.
+For example:
+
+```bash
+conda_envfile_diff env1.yml env2.yml
+```
+
 ## pre-commit
 
+### conda_envfile_parse
+
+Keep your `environment.yaml` file unique, sorted, and legal in terms of version limitations.
 In your `.pre-commit-config.yaml`, add:
 
 ```yaml
 - repo: https://github.com/tdegeus/conda_envfile
-  rev: v0.2.1
+  rev: v0.5.0
   hooks:
   - id: conda_envfile_parse
     files: "environment.yaml"
 ```
 
-to keep your `environment.yaml` file unique, sorted, and legal in terms of version limitations.
+### conda_envfile_pyproject
+
+Keep your `pyproject.toml` and `environment.yaml` in sync.
+In your `.pre-commit-config.yaml`, add:
+
+```yaml
+- repo: https://github.com/tdegeus/conda_envfile
+  rev: v0.5.0
+  hooks:
+  - id: conda_envfile_pyproject
+    files: "environment.yaml"
+```
 
 ## Python
 

conda_envfile/__init__.py

@@ -1133,7 +1133,9 @@ def _conda_envfile_parse_parser():
     """
 
     desc = """
-    Parse YAML environment files, formatted::
+    Parse conda environment files.
+    This keeps the list of packages unique, sorted, and with legal versions.
+    It assumes YAML-files formatted like::
 
         name: ...
         channels:
@@ -1176,7 +1178,9 @@ def _conda_envfile_merge_parser():
     """
 
     desc = """
-    Merge YAML environment files, formatted::
+    Merge conda environment files.
+    This creates a list of packages that is unique, sorted, and with the most restrictive versions.
+    It assumes YAML-files formatted like::
 
         name: ...
         channels:
@@ -1418,7 +1422,9 @@ def _conda_envfile_pyproject_parser():
     """
 
     desc = """
-    Compare the dependencies in a ``pyproject.toml`` file with a conda ``environment.yaml`` file.
+    Sync the version limitations in a ``pyproject.toml`` file and a conda ``environment.yaml`` file.
+    Optionally, all missing dependencies in one or the other can be added
+    (``--from-pyproject`` or ``--from-environment``).
 
     .. note::
 

docs/conf.py

@@ -13,6 +13,7 @@
     "sphinx.ext.todo",
     "sphinxarg.ext",
     "sphinx.ext.autosectionlabel",
+    "sphinx_mdinclude",
 ]
 
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

docs/index.rst

@@ -17,6 +17,8 @@
   `www.geus.me <http://www.geus.me>`_ |
   `github.com/tdegeus/conda_envfile <http://github.com/tdegeus/conda_envfile>`_
 
+.. mdinclude:: ../README.md
+
 Contents
 ========
 

docs/tools.rst

@@ -2,10 +2,42 @@
 Command-line tools
 ******************
 
+conda_envfile_parse
+===================
+
+.. argparse::
+    :module: conda_envfile
+    :func: _conda_envfile_parse_parser
+    :prog: conda_envfile_parse
+
 conda_envfile_merge
 ===================
 
 .. argparse::
     :module: conda_envfile
     :func: _conda_envfile_merge_parser
     :prog: conda_envfile_merge
+
+conda_envfile_diff
+==================
+
+.. argparse::
+    :module: conda_envfile
+    :func: _conda_envfile_diff_parser
+    :prog: conda_envfile_diff
+
+conda_envfile_pyproject
+=======================
+
+.. argparse::
+    :module: conda_envfile
+    :func: _conda_envfile_pyproject_parser
+    :prog: conda_envfile_pyproject
+
+conda_envfile_restrict
+======================
+
+.. argparse::
+    :module: conda_envfile
+    :func: _conda_envfile_restrict_parser
+    :prog: conda_envfile_restrict

environment.yaml

@@ -13,3 +13,4 @@ dependencies:
 - setuptools_scm
 - sphinx
 - sphinx-argparse
+- sphinx-mdinclude