enhancement #37: generate doc with pdoc

Author: FabienDanieau

.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Generate Python Documentation
+
+on: [pull_request]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-22.04
+    steps:
+    - name: Checkout Repository
+      uses: actions/checkout@v3
+
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+
+    - name: Install Dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install .[dev]
+
+    - name: Generate Documentation
+      run: pdoc example --output-dir docs
+
+    - name: Archive Documentation
+      uses: actions/upload-artifact@v4
+      with:
+        name: documentation
+        path: docs/

.gitignore

@@ -163,3 +163,8 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# generate documentation
+docs/*.html
+docs/*.js
+docs/example/

README.md

@@ -143,4 +143,12 @@ Then, if all tests are sucessful:
  The main guidelines for the coding style is defined by [PEP8](https://peps.python.org/pep-0008/). You can directly refer to the examples in the code.
 
  Specific choices are detailed in dedicated document:
- - for the mathematical notation please refer to [Coding convention for Maths](docs/convention_maths.md)
+ - for the mathematical notation please refer to [Coding convention for Maths](docs/convention_maths.md)
+
+ ## Documentation
+
+The documentation is generated with [pdoc](https://pdoc.dev), automatically with the CI. To generate it locally you can run:
+
+```
+ pdoc example --output-dir docs
+ ```

setup.cfg

@@ -32,6 +32,7 @@ dev = black==24.10.0
       coverage==7.3.2
       mypy==1.8.0
       isort==5.13.2
+      pdoc==14.7.0
 
 [options.entry_points]
 console_scripts =