Merge pull request #3 from MilieuCentrumUtrecht/docs

This PR adds the following features:

- Run CodeQL (code quality) and OSSAR (security) on special branch names main CI ci, and docs
- Rename package generation to Package with Conda
- Add sphinx-quickstart files and sphinx-using-conda.yml workflow file to auto-generate documentation

More information can be found at:

- Sphinx: https://www.sphinx-doc.org/en/master/#get-started
- OSSAR: https://github.com/MilieuCentrumUtrecht/Snuffelfiets/actions/new?category=none&query=ossar
- CodeQL: https://github.com/MilieuCentrumUtrecht/Snuffelfiets/actions/new?category=none&query=codeQL

.gitattributes

@@ -0,0 +1 @@
+src/snuffelfiets/_version.py export-subst

.github/workflows/codeql.yml

@@ -13,9 +13,11 @@ name: "CodeQL Advanced"
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "main", "CI", "ci", "docs" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "main"]
+    # A pull request almost always starts with a push (I guess) so avoid duplication
+    types: [opened, reopened, review_requested, auto_merge_enabled]
   schedule:
     - cron: '38 9 * * 1'
 

.github/workflows/ossar.yml

@@ -10,10 +10,11 @@ name: OSSAR
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "main", "CI", "ci", "docs" ]
   pull_request:
-    # The branches below must be a subset of the branches above
-    branches: [ "main" ]
+    branches: [ "main"]
+    # A pull request almost always starts with a push (I guess) so avoid duplication
+    types: [opened, reopened, review_requested, auto_merge_enabled]
   schedule:
     - cron: '27 15 * * 2'
 

.github/workflows/package-with-conda.yml

@@ -0,0 +1,82 @@
+name: 🐍 Package 📦 with Conda and PyPI
+
+on:
+  push:
+    branches: [ "main", "CI", "ci", "docs" ]
+  pull_request:
+    branches: [ "main"]
+    # A pull request almost always starts with a push (I guess) so avoid duplication
+    types: [opened, reopened, review_requested, auto_merge_enabled]
+
+jobs:
+  build-linux:
+    runs-on: ubuntu-latest
+
+    strategy:
+      max-parallel: 5
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.10'
+    - name: Add conda to system path
+      run: |
+        # $CONDA is an environment variable pointing to the root of the miniconda directory
+        echo $CONDA/bin >> $GITHUB_PATH
+    - name: Install dependencies
+      run: |
+        conda install -n base --force-reinstall conda-libmamba-solver # Fix mambda solver
+        conda env update --file environment.yml --name base
+        conda config --set solver classic
+    - name: Lint with flake8
+      run: |
+        conda install flake8
+        # stop the build if there are Python syntax errors or undefined names
+        #flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      run: |
+        conda install pytest
+        pip install -e .
+        pytest
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-testpypi:
+    name: Publish Python 🐍 distribution 📦 to TestPyPI
+    needs:
+    - build-linux
+    runs-on: ubuntu-latest
+
+    environment:
+      name: default
+      url: https://test.pypi.org/p/snuffelfiets
+
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    # This should only be done when testing
+    #- name: Publish distribution 📦 to TestPyPI
+    #  uses: pypa/gh-action-pypi-publish@release/v1
+    #  with:
+    #    repository-url: https://test.pypi.org/legacy/

.github/workflows/sphinx-using-conda.yml

@@ -0,0 +1,58 @@
+name: Sphinx using Conda
+
+on:
+  push:
+    branches: [ "main", "CI", "ci", "docs" ]
+  pull_request:
+    branches: [ "main"]
+    # A pull request almost always starts with a push (I guess) so avoid duplication
+    types: [opened, reopened, review_requested, auto_merge_enabled]
+
+jobs:
+  build-linux:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 5
+      fail-fast: false
+      matrix:
+        python-version: ["3.10"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Setup Pages
+      uses: actions/configure-pages@v5
+    - name: Add conda to system path
+      run: |
+        # $CONDA is an environment variable pointing to the root of the miniconda directory
+        echo $CONDA/bin >> $GITHUB_PATH
+    - name: Install dependencies
+      run: |
+        conda env update --file environment.yml --name base
+    - name: Build docs with Sphinx
+      run: |
+        conda install sphinx
+        python setup.py develop
+        make -C docs html
+    - name: Upload artifact
+      id: deployment-1
+      uses: actions/upload-pages-artifact@v3
+      with:
+        # Upload entire HTML pages folder
+        path: docs/build/html/
+  deploy:
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build-linux
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/.gitignore

@@ -0,0 +1 @@
+generated/

docs/source/_templates/custom-module-template.rst

@@ -0,0 +1,66 @@
+{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules | reject("equalto", "test") %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/source/api-hidden.rst

@@ -0,0 +1,6 @@
+.. autosummary::
+   :toctree: generated/
+   :recursive:
+   :template: custom-module-template.rst
+
+   snuffelfiets

docs/source/api.rst

@@ -0,0 +1,20 @@
+.. currentmodule:: snuffelfiets
+
+API reference
+=============
+
+This page provides an auto-generated summary of Snuffelfiets's API. For more details
+and examples, refer to the relevant chapters in the main part of the
+documentation.
+
+IMASPy IDS manipulation
+-------------------------
+
+.. currentmodule:: snuffelfiets
+
+.. autosummary::
+
+   analyse
+   inlezen
+   opschonen
+   plotting