Merge pull request #22 from mscheltienne/doc-build

Documentation build

.github/workflows/code-style.yml

@@ -24,10 +24,8 @@ jobs:
         run: |
           python -m pip install --progress-bar off --upgrade pip setuptools wheel
           python -m pip install --progress-bar off .[style]
-      - name: Run flake8
-        uses: py-actions/flake8@v2
-        with:
-          path: "lapy"
+      - name: Run Ruff
+        run: ruff check .
       - name: Run isort
         uses: isort/isort-action@master
       - name: Run black
@@ -41,5 +39,7 @@ jobs:
           check_hidden: true
           skip: './.git,./build,./.mypy_cache,./.pytest_cache'
           ignore_words_file: ./.codespellignore
-      # - name: Run pydocstyle
-      #   run: pydocstyle .
+      - name: Run pydocstyle
+        run: pydocstyle .
+      - name: Run bibclean
+        run: bibclean-check doc/references.bib

.github/workflows/doc.yml

@@ -0,0 +1,65 @@
+name: doc
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
+  cancel-in-progress: true
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  build:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          path: ./main
+      - name: Setup Python 3.9
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+          architecture: 'x64'
+      - name: Install package
+        run: |
+          python -m pip install --progress-bar off --upgrade pip setuptools wheel
+          python -m pip install --progress-bar off main/.[doc]
+      - name: Display system information
+        run: lapy-sys_info --developer
+      - name: Build doc
+        run: sphinx-build ./main/doc ./doc-build/dev -W --keep-going
+      - name: Upload documentation
+        uses: actions/upload-artifact@v3
+        with:
+          name: doc-dev
+          path: ./doc-build/dev
+
+  deploy:
+    if: github.event_name == 'push'
+    needs: build
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Download documentation
+        uses: actions/download-artifact@v3
+        with:
+          name: doc-dev
+          path: ./doc-dev
+      - name: Deploy dev documentation
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./doc-dev
+          destination_dir: ./dev
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'

doc/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     = .
+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)

doc/_templates/autosummary/class.rst

@@ -0,0 +1,10 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :inherited-members:
+
+.. minigallery:: {{ fullname }}
+    :add-heading:

doc/_templates/autosummary/function.rst

@@ -0,0 +1,8 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. minigallery:: {{ fullname }}
+    :add-heading:

doc/api/index.rst

@@ -0,0 +1,11 @@
+API References
+==============
+
+This is the reference for classes (``CamelCase`` names) and functions
+(``underscore_case`` names) of ``lapy`` grouped thematically.
+
+.. toctree::
+    :maxdepth: 2
+
+    lapy.meshes.rst
+    lapy.solver.rst

doc/api/lapy.meshes.rst

@@ -0,0 +1,10 @@
+Meshes
+======
+
+.. currentmodule:: lapy
+
+.. autosummary::
+    :toctree: generated/
+
+    TriaMesh
+    TetMesh

doc/api/lapy.solver.rst

@@ -0,0 +1,9 @@
+Solver
+======
+
+.. currentmodule:: lapy
+
+.. autosummary::
+    :toctree: generated/
+
+    Solver

doc/changes/authors.inc

@@ -0,0 +1,4 @@
+.. _Andreas Girodi: https://github.com/agirodi
+.. _Kersten Diers: https://github.com/kdiers
+.. _Martin Reuter: https://github.com/m-reuter
+.. _Mathieu Scheltienne: https://github.com/mscheltienne

doc/changes/index.rst

@@ -0,0 +1,7 @@
+Changelog
+=========
+
+.. toctree::
+    :titlesonly:
+
+    latest.rst

doc/changes/latest.rst

@@ -0,0 +1,42 @@
+.. NOTE: we use cross-references to highlight new functions and classes.
+   Please follow the examples below, so the changelog page will have a link to
+   the function/class documentation.
+
+.. NOTE: there are 3 separate sections for changes, based on type:
+   - "Enhancements" for new features
+   - "Bugs" for bug fixes
+   - "API changes" for backward-incompatible changes
+
+.. NOTE: You can use the :pr:`xx` and :issue:`xx` role to x-ref to a GitHub PR
+   or issue from this project.
+
+.. include:: ./authors.inc
+
+.. _latest:
+
+Version 0.7
+===========
+
+Enhancements
+------------
+
+- Comply with the numpy convention for docstrings (by `Andreas Girodi`_, `Kersten Diers`_ and `Martin Reuter`_ in :pr:`19` and :pr:`21`)
+- Add documentation build (by `Mathieu Scheltienne`_ in :pr:`22`)
+
+Bugs
+----
+
+- xxx
+
+API and behavior changes
+------------------------
+
+- xxx
+
+Authors
+-------
+
+* `Andreas Girodi`_
+* `Kersten Diers`_
+* `Martin Reuter`_
+* `Mathieu Scheltienne`_

doc/changes/latest.rst.template

@@ -0,0 +1,38 @@
+.. NOTE: we use cross-references to highlight new functions and classes.
+   Please follow the examples below, so the changelog page will have a link to
+   the function/class documentation.
+
+.. NOTE: there are 3 separate sections for changes, based on type:
+   - "Enhancements" for new features
+   - "Bugs" for bug fixes
+   - "API changes" for backward-incompatible changes
+
+.. NOTE: You can use the :pr:`xx` and :issue:`xx` role to x-ref to a GitHub PR
+   or issue from this project.
+
+.. include:: ./authors.inc
+
+.. _latest:
+
+Version x.x
+===========
+
+Enhancements
+------------
+
+- xxx
+
+Bugs
+----
+
+- xxx
+
+API and behavior changes
+------------------------
+
+- xxx
+
+Authors
+-------
+
+* `Mathieu Scheltienne`_