ADD-FIX: minor infos to documentation

Author: 9and3

.github/workflows/documentation.yml

@@ -71,17 +71,21 @@ jobs:
           auto-update-conda: true
           python-version: 3.9.1
 
-      - name: Restore conda environment cache
-        uses: actions/cache@v2
-        with:
-          path: C:\Miniconda\envs\diff_check
-          key: ${{ runner.os }}-conda-${{ hashFiles('environment.yml') }}
-          restore-keys: |
-            ${{ runner.os }}-conda-
+      # - name: Restore conda environment cache
+      #   uses: actions/cache@v2
+      #   with:
+      #     path: C:\Miniconda\envs\diff_check
+      #     key: ${{ runner.os }}-conda-${{ hashFiles('environment.yml') }}
+      #     restore-keys: |
+      #       ${{ runner.os }}-conda-
 
-      # - name: Activate diff_check conda environment
-      #   run: |
-      #     conda activate diff_check
+      - name: Create diff_check conda environment
+        run: |
+          conda env create -f environment.yml
+
+      - name: Activate diff_check conda environment
+        run: |
+          conda activate diff_check
 
       - name: Download dlls/pyd artifacts
         uses: actions/download-artifact@v2
@@ -106,8 +110,7 @@ jobs:
 
       - name: Sphinx build
         run: |
-          conda activate diff_check
-          sphinx-build doc _build
+          conda run --name diff_check --no-capture-output sphinx-build doc _build
         working-directory: ${{github.workspace}}
 
 

doc/documentation.md

@@ -3,6 +3,20 @@
 
 In DF we use `Sphinx` to generate the documentation. The documentation is written in `reStructuredText` and `Markdown` and the source files are located in the `doc` folder. The documentation is hosted on `ReadTheDocs` and is automatically updated when a new commit is pushed to the `main` branch.
 
+## Build locally
+
+To build locally the documentation to test your changes:
+```console
+invoke documentize
+```
+and to open the documentation in your browser:
+```console
+start _build/html/index.html
+```
+If you modify the `doc`s files and refresh the pages updates will be visible.
+
+## Contribute to the documentation
+
 Follow these guides to contribute to the documentation whether you:
 
 - add a new [GHComponents](ghcomp_doc_g)
@@ -11,7 +25,7 @@ Follow these guides to contribute to the documentation whether you:
 
 ---
 (ghcomp_doc_g)=
-## `GHComponent`'s docs
+### ✔️ `GHComponent`'s docs
 
 If you write a new [GHComponents](gh_components.rst) you will most probably already have created and filled a `metadata.json` file. DF uses this file to automatically generate the documentation for the GHComponents. The only thing you need to do is:
 * add a new `.rst` file with the name of the component like `gh_DFComponentName.rst`
@@ -24,7 +38,7 @@ Our custom sphinx extension `sphinx_ghcomponent_parser` will automatically parse
 
 
 (pyapi_doc_g)=
-## `Python API`'s docs
+### ☑️ `Python API`'s docs
 
 For [Python API documentation](diffCheck_PythonAPI), we use `sphinx-apidoc` to automatically generate the API documentation so the only thing to do is to add beautiful docstrings to the Python code with the following reStructuredText (reST) format style:
 
@@ -44,7 +58,7 @@ For [Python API documentation](diffCheck_PythonAPI), we use `sphinx-apidoc` to a
 ```
 
 (tutorial_doc_g)=
-## `DF Tutorial`'s docs
+### ✅ `DF Tutorial`'s docs
 
 If you need to add a new page to the [tutorials](tutorials.rst) (e.g. a [new tutorial](tutorials.rst)), you can do so by adding a new `.rst` file in the `doc` folder and linking it in the `tutorials.rst` file's toctree: