Add autogenerated documentation (#4)

* Add various files needed for config

* Rewrite  API generation

* Add build and upload docs

* Fix copying of readme

* Fix make

Author: jorgensd

.github/workflows/build_docs.yml

@@ -0,0 +1,29 @@
+name: Github Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install ".[docs]"
+      - name: Build docs
+        run: make doc
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_build/html

.github/workflows/test_package.yml

@@ -54,6 +54,18 @@ jobs:
           path: htmlcov
           if-no-files-found: error
 
+      - name: Build documentation
+        run: |
+           make doc
+
+      - name: Upload documentation
+        uses: actions/upload-artifact@v3
+        with:
+          name: documentation
+          path: docs/_build/html
+          if-no-files-found: error
+
+
   test-code:
     # This code depends on the result of check-code
     needs: check-code

Makefile

@@ -0,0 +1,18 @@
+doc: # Generate Sphinx HTML documentation, including API docs
+	cp README.md docs/README.md
+	jupyter book build docs
+
+clean-pytest: # Remove output from pytest
+	rm -rf .pytest_cache
+	rm -rf test/__pycache__
+
+clean-coverage: # Remove output from coverage
+	rm -rf .covarge htmlcov
+
+clean-mypackage: # Remove output from installing package
+	rm -rf mypackage.egg-info mypackage/__pycache__
+
+clean-mypy: # Remove output from mypy
+	rm -rf .mypy_cache
+
+clean: clean-mypy clean-mypackage clean-coverage clean-pytest

docs/_config.yml

@@ -0,0 +1,40 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: MyPackage - The reproducible template for Simula Research Laboratory
+author: Jørgen S. Dokken
+logo: "logo.png"
+copyright: "2022"
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/jorgensd/reproducibility # Online location of your book
+  path_to_book: docs # Optional path to your book, relative to the repository root
+  branch: main # Which branch of the repository should be used when creating links (optional)
+
+
+sphinx:
+  extra_extensions:
+  - 'sphinx.ext.autodoc'
+  - 'sphinx.ext.napoleon'
+  - 'sphinx.ext.viewcode'
+
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+
+
+parse:
+  myst_enable_extensions:
+    - amsmath
+    - dollarmath
+    - linkify

docs/_toc.yml

@@ -0,0 +1,5 @@
+format: jb-book
+root: README
+
+chapters:
+  - file: "api"

docs/api.rst

@@ -0,0 +1,5 @@
+API Reference
+=============
+
+.. automodule:: mypackage
+    :members:

docs/logo.png

@@ -4,6 +4,6 @@
 # This file is part of my_package
 # SPDX-License-Identifier:    MIT
 
-from .functions import addition
+from .functions import addition, print_add
 
-__all__ = ["addition"]
+__all__ = ["addition", "print_add"]

mypackage/__init__.py

@@ -5,12 +5,16 @@
 # This file is part of mypackage
 # SPDX-License-Identifier:    MIT
 
+__all__ = ["addition", "print_add"]
+
+
 def addition(a: int, b: int) -> int:
     """ Computes a+b """
     return a + b
 
 
 def print_add(a: int, b: int) -> int:
+    """ Computes and prints a + b"""
     c = a + b
     print(c)
     return c

mypackage/functions.py

@@ -26,7 +26,7 @@ test = [
 ]
 
 docs = [
-    "Sphinx",
+    "sphinx",
     "jupyter-book",
     "pandoc"
 ]