Merge pull request #14 from scientificcomputing/dokken/documentation

Initial thoughts regarding documentation
scientificcomputing · Nov 20, 2023 · ee5cf56 · ee5cf56
2 parents 5fc41aa + 8e4fd13
commit ee5cf56
Show file tree

Hide file tree

Showing 6 changed files with 124 additions and 63 deletions.
diff --git a/code/1-documentation-simple/README.md b/code/1-documentation-simple/README.md
@@ -1,3 +1,43 @@
 # Documentation basic
 
-Here is an example of basic documentation with jupyter-book
+Here is an example of basic documentation with [jupyter-book](https://jupyterbook.org/) and some of the features of markdown.
+
+We can get a breakdown of the current page by adding sub-headings by using `##` for a second level heading, and `###` for a third level heading etch
+
+## Subheading
+
+Here we have some more text.
+We can add a block of code with 3x` syntax, i.e.
+````
+```python
+import numpy as np
+# Here is a comment
+```
+````
+### Code example
+The above code would render as
+```python
+import numpy as np
+# Here is a comment
+```
+
+## New sub heading
+You can also add more fancy things, such as a note
+```{note}
+This is a note
+```
+and warnings
+```{warning}
+I warn you
+```
+### References
+We add a bibliography file `references.bib` to our repo, and cite things as
+{cite}`Yogi2018`
+See: [Jupyter-book: Citations](https://jupyterbook.org/en/stable/content/citations.html) for more information
+
+
+## Bibliography
+```{bibliography}
+:style: alpha
+:filter: docname in docnames
+```
diff --git a/code/1-documentation-simple/_config.yml b/code/1-documentation-simple/_config.yml
@@ -3,16 +3,17 @@ title: Example paper
 author: Henrik Finsberg and Jørgen Dokken
 copyright: "2023"
 only_build_toc_files: true
+bibtex_bibfiles: "references.bib"
 
 parse:
   myst_enable_extensions:
     - amsmath
     - dollarmath
     - linkify
 
-
 sphinx:
   config:
+    bibtex_reference_style: author_year
     nb_execution_show_tb: True
     html_theme_options:
       navigation_with_keys: false
@@ -22,9 +23,4 @@ sphinx:
             - jupytext.reads
             - fmt: py
 
-  extra_extensions:
-  - 'sphinx.ext.autodoc'
-  - 'sphinx.ext.napoleon'
-  - 'sphinx.ext.viewcode'
-
 exclude_patterns: [".pytest_cache/*", ".github/*"]
diff --git a/code/1-documentation-simple/pyproject.toml b/code/1-documentation-simple/pyproject.toml
@@ -7,9 +7,12 @@ name = "documentation-basic"
 version = "0.1.0"
 dependencies = []
 
-
 [project.optional-dependencies]
 docs = [
     "jupyter-book",
     "jupytext",
+    "docutils==0.17.1"
 ]
+
+[tool.setuptools]
+packages = []
diff --git a/code/1-documentation-simple/references.bib b/code/1-documentation-simple/references.bib
@@ -0,0 +1,11 @@
+@inproceedings{Yogi2018,
+ author = {Zaheer, Manzil and Reddi, Sashank and Sachan, Devendra and Kale, Satyen and Kumar, Sanjiv},
+ booktitle = {Advances in Neural Information Processing Systems},
+ editor = {S. Bengio and H. Wallach and H. Larochelle and K. Grauman and N. Cesa-Bianchi and R. Garnett},
+ pages = {},
+ publisher = {Curran Associates, Inc.},
+ title = {Adaptive Methods for Nonconvex Optimization},
+ url = {https://proceedings.neurips.cc/paper_files/paper/2018/file/90365351ccc7437a1309dc64e4db32a3-Paper.pdf},
+ volume = {31},
+ year = {2018}
+}
diff --git a/cspell.json b/cspell.json
@@ -7,12 +7,16 @@
         "amsmath",
         "autodoc",
         "bibtex",
+        "bibfiles",
         "bioconda",
         "cookiecutter",
         "Cookiecutters",
         "Diataxis",
         "directivename",
+        "docname",
+        "docnames",
         "docstrings",
+        "docutils",
         "Dokken",
         "dolfinx",
         "dollarmath",

diff --git a/docs/documentation.md b/docs/documentation.md
@@ -1,8 +1,8 @@
 ---
 theme: default
 paginate: true
-header: 'Best Practices in Modern Software Development: Documentation'
-footer: '23.11.23 - Jørgen Dokken'
+header: "Best Practices in Modern Software Development: Documentation"
+footer: "23.11.23 - Jørgen Dokken"
 size: 16:9
 style: |
   .small-text {
@@ -13,21 +13,21 @@ marp: true
 ---
 
 # Documentation
+
 Best Practices in Modern Software Development: 23.11.23
 
 Jørgen Dokken
 
-
 ---
 
 ## What is documentation?
 
 * Background and motivation
-    - What do you try to solve?
+  * What do you try to solve?
 * Instructions on how to install the software and necessary dependencies
 * Instructions on how to use the software
-    - Tutorials / demos
-    - API documentation
+  * Tutorials / demos
+  * API documentation
 * Instructions on how to get help or contribute
 * https://diataxis.fr/
 
@@ -37,7 +37,6 @@ Jørgen Dokken
 
 * Make it easier for users (including yourself) to understand and use your code
 * Make it easier for other to contribute (file issues / fix bugs)
-* Which will make your software better
 
 ---
 
@@ -52,29 +51,29 @@ Jørgen Dokken
 
 ---
 
-- Could include
+## The README file (continued)
+
+- ### Optional
   - Badges
   - Information about how to contribute
   - License information
   - Credits
   - Example
   - How to cite
   - Screenshots / figures
-- https://readme.so
-
+* README skeleton generator: https://readme.so
 
 ---
 
-
 ## Using JupyterBook to create documentation
 
 - [JupyterBook](https://jupyterbook.org/en/stable/intro.html) is a powerful framework for writing documentation
-- You can use Markdown (Myst), Notebooks and pure python files in your documentation.
-- It integrates well with latex (math) and Sphinx (for parsing docstrings)
+* You can use Markdown (Myst), Notebooks and pure Python files in your documentation.
+* It integrates well with LaTeX (math) and Sphinx (for parsing docstrings)
 
 ---
 
-## Add extra dependencies for docs
+## Add extra dependencies to `pyproject.toml` for docs
 
 To use `jupyter-book` in your project you should add some extra dependencies
 
@@ -84,6 +83,8 @@ docs = [
     "jupyter-book",
     "jupytext",
     "sphinxcontrib-bibtex",
+    "docutils==0.17.1"
+    # Temporary pin due to https://sourceforge.net/p/docutils/patches/195/
 ]
 ```
 
@@ -92,31 +93,31 @@ docs = [
 ## Compile the exact versions your use with pip-compile
 
 Use
+
 ```
 pip-compile --extra=docs --output-file=requirements-docs.txt pyproject.toml
 ```
 
-
 ---
 
-## Need to create a config file called `_config.yml`
-
+## Documentation configuration
 ```yaml
 # _config.yml
 title: Example paper
 author: Henrik Finsberg and Jørgen Dokken
 copyright: "2023"
 only_build_toc_files: true
+bibtex_bibfiles: "references.bib"
 
 parse:
   myst_enable_extensions:
     - amsmath
     - dollarmath
     - linkify
 
-
 sphinx:
   config:
+    bibtex_reference_style: author_year
     nb_execution_show_tb: True
     html_theme_options:
       navigation_with_keys: false
@@ -126,11 +127,6 @@ sphinx:
             - jupytext.reads
             - fmt: py
 
-  extra_extensions:
-  - 'sphinx.ext.autodoc'
-  - 'sphinx.ext.napoleon'
-  - 'sphinx.ext.viewcode'
-
 exclude_patterns: [".pytest_cache/*", ".github/*"]
 ```
 
@@ -153,11 +149,13 @@ chapters:
 ## Building the book
 
 Install JupyterBook
+
 ```
 python3 -m pip install jupyter-book
 ```
 
 Build the book (in the root where `_config.yml` amd `_toc.yml` is located).
+
 ```
 jupyter-book build .
 ```
@@ -168,40 +166,21 @@ Demo `code/1-documentation-basic`
 
 ---
 
-## Documenting code using docstrings and type hints
-
-- There are standard ways to document your code
-
-- We recommend to use either the Google style or Numpy style
-
-- https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#google-vs-numpy
-
-
----
-
-## VSCode extension to generate docstrings
-
-https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring
-
-![w:700 center](https://github.com/NilsJPWerner/autoDocstring/raw/HEAD/images/demo.gif)
-
----
-
 ## Using MyST-Markdown to write content
 
-- JupyterBook support a flavor of Markdown called *MyST*.
+- JupyterBook support a flavor of Markdown called _MyST_.
 - Here you write so called directives
-    ````
-    ```{directivename}
-    Content
-    ```
-    ````
-    e.g
-    ````
-    ```{math}
-    x^2 + y^2 = z^2
-    ```
-    ````
+  ````
+  ```{directivename}
+  Content
+  ```
+  ````
+  e.g
+  ````
+  ```{math}
+  x^2 + y^2 = z^2
+  ```
+  ````
 
 ---
 
@@ -215,7 +194,9 @@ It is also possible to use MyST to labels to equations
 w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}
 ```
 ````
+
 and then use
+
 ```
 - A link to an equation directive: {eq}`my_label`
 ```
@@ -319,7 +300,7 @@ name: Github Pages
 
 on:
   push:
-    branches: [main]  # Only run on push to main
+    branches: [main] # Only run on push to main
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
@@ -367,3 +348,29 @@ jobs:
         id: deployment
         uses: actions/deploy-pages@v2
 ```
+
+---
+## API documentation
+
+- Jupyter-book supports auto-documentation features from Sphinx.
+- More information at: https://jupyterbook.org/en/stable/advanced/developers.html?highlight=api#developer-workflows
+
+---
+
+## Documenting code using docstrings and type hints
+
+- There are standard ways to document your code
+
+- We recommend to use either the Google style or Numpy style
+
+  - https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#google-vs-numpy
+
+---
+
+## VSCode extension to generate docstrings
+
+https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring
+
+![w:700 center](https://github.com/NilsJPWerner/autoDocstring/raw/HEAD/images/demo.gif)
+
+---