docs: update doc-environment.yml file and Documentation Setup documentation (#3058)

vandalt · web-flow · commit a540a2ec083f · 2024-09-04T10:35:58.000+02:00
This PR fixes #3054 by updating the `doc-environment.yml` file: - Add `sphinxawesome-theme`, `snakemake-interface-common >=1.17.0`, `snakemake-interface-executor-plugins >=9.1.0`, `snakemake-interface-storage-plugins >=3.2.3` dependencies - Replace `ratelimiter` by `throttler` - Update required Python version from 3.7 to 3.11 Another option which I mentioned in #3054 would be to merge the `test-environment.yml` and `doc-environment.yml`. Let me know if you would prefer this. ### QC  * [x] The PR contains a test case for the changes or the changes are already covered by an existing test case. (N.A.) * [x] The documentation (`docs/`) is updated to reflect the changes or this is not necessary (e.g. if the change does neither modify the language nor the behavior or functionalities of Snakemake).  ## Summary by CodeRabbit - **New Features** - Updated Python version requirement to 3.11 for improved functionality. - Added new dependencies to enhance environment capabilities. - Introduced improved documentation styling options with `sphinxawesome-theme`. - Added instructions for installing the development version of Snakemake in the contributing guide. - **Bug Fixes** - Corrected hyperlink references in documentation for clarity and accuracy. - **Documentation** - Enhanced clarity and precision in descriptions related to modular workflows. - Updated terminology throughout documentation for consistency. - Improved navigation and accessibility of documentation links.
diff --git a/doc-environment.yml b/doc-environment.yml
@@ -1,23 +1,27 @@
 channels:
   - conda-forge
 dependencies:
-  - python >=3.7
+  - python >=3.11
   - datrie
   - wrapt
   - pyyaml
   - requests
   - appdirs
   - docutils
-  - ratelimiter
+  - throttler
   - configargparse
   - jsonschema
   - gitpython
   - sphinx
   - pip
   - pip:
     - sphinxcontrib-napoleon
+    - snakemake-interface-common >=1.17.0
+    - snakemake-interface-executor-plugins >=9.1.0
+    - snakemake-interface-storage-plugins >=3.2.3
   - sphinx-argparse
   - sphinx_rtd_theme
+  - sphinxawesome-theme
   - docutils
   - recommonmark
   - commonmark
diff --git a/docs/project_info/contributing.rst b/docs/project_info/contributing.rst
@@ -186,6 +186,12 @@ Snakemake development environment via
     $ cd snakemake
     $ conda env create -f doc-environment.yml -n snakemake
 
+You will also need to install your development version of Snakemake for the docs to be built correctly
+
+.. code-block:: console
+
+    $ pip install -e .
+
 Then, the docs can be built with
 
 .. code-block:: console
