starting docs with jupyter book and sphinx

Author: dehann

.github/workflows/documentation.yml

@@ -0,0 +1,43 @@
+# https://stackoverflow.com/a/58008902
+release_sphinx:
+  needs: [build]
+  runs-on: ubuntu-latest
+  container:
+    image: python:3.6
+    volumes:
+      - dist:dist
+      - public:public
+  steps:
+
+    # check out sources that will be used for autodocs, plus readme
+    - uses: actions/checkout@v1
+
+    # download wheel that was build and uploaded in the build step
+    - uses: actions/download-artifact@v1
+      with:
+        name: distributions
+        path: dist
+
+    # didn't need to change anything here, but had to add sphinx.ext.githubpages
+    # to my conf.py extensions list. that fixes the broken uploads
+    - name: Building documentation
+      run: |
+        pip install dist/*.whl
+        pip install sphinx Pallets-Sphinx-Themes
+        sphinx-apidoc --no-toc --module-first -o docs/autodoc src/stenotype
+        sphinx-build docs public -b dirhtml
+
+    # # still need to build and set the PAT to get a rebuild on the pages job,
+    # # apart from that quite clean and nice 
+    # - name: github pages deploy
+    #   uses: peaceiris/actions-gh-pages@v2.3.1
+    #   env:
+    #     PERSONAL_TOKEN: ${{ secrets.PAT }}
+    #     PUBLISH_BRANCH: gh-pages
+    #     PUBLISH_DIR: public
+
+    # # # since gh-pages has a history, this step might no longer be necessary.
+    # # - uses: actions/upload-artifact@v1
+    # #   with:
+    # #     name: documentation
+    # #     path: public

.gitignore

@@ -118,3 +118,5 @@ venv/
 venv_test/
 
 sandbox.py
+
+docs/_build

docs/README.md

@@ -0,0 +1,27 @@
+# How to Docs
+
+## Building the Docs
+
+```
+# go repo root folder
+cd NavAbilitySDK.py
+
+# Install required Python dependencies (Sphinx etc.)
+pip install -r docs/requirements.txt
+
+# Run Jupyter Book
+jupyter-book build docs/
+
+# View the docs with for instance firefox
+firefox docs/_build/index.html
+```
+
+## Resources
+
+This documentation folder is based on work from:
+- https://github.com/readthedocs-examples/example-jupyter-book
+
+With auto docstring extension:
+- https://jupyterbook.org/en/stable/advanced/developers.html?highlight=docstrings#api-reference-from-docstrings
+
+

docs/_config.yml

@@ -0,0 +1,76 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+# Comprehensive example: https://github.com/executablebooks/jupyter-book/blob/master/docs/_config.yml
+
+title: Example Jupyter Book for Read the Docs
+author: Read the Docs team
+logo: logo.png
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+  - references.bib
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/readthedocs-examples/example-jupyter-book  # 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)
+
+# 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
+
+sphinx:
+  config:
+    intersphinx_mapping:
+      ebp:
+        - "https://executablebooks.org/en/latest/"
+        - null
+      myst-parser:
+        - "https://myst-parser.readthedocs.io/en/latest/"
+        - null
+      myst-nb:
+        - "https://myst-nb.readthedocs.io/en/latest/"
+        - null
+      sphinx:
+        - "https://www.sphinx-doc.org/en/master"
+        - null
+      nbformat:
+        - "https://nbformat.readthedocs.io/en/latest"
+        - null
+      sd:
+        - "https://sphinx-design.readthedocs.io/en/latest"
+        - null
+      sphinxproof:
+        - "https://sphinx-proof.readthedocs.io/en/latest/"
+        - null
+    hoverxref_intersphinx:
+     - "sphinxproof"
+    mathjax3_config:
+      tex:
+        macros:
+          "N": "\\mathbb{N}"
+          "floor": ["\\lfloor#1\\rfloor", 1]
+          "bmat": ["\\left[\\begin{array}"]
+          "emat": ["\\end{array}\\right]"]
+        
+  extra_extensions:
+    - sphinx.ext.intersphinx
+    - sphinx.ext.autodoc
+    - sphinx_inline_tabs
+    - sphinx_proof
+    - sphinx_examples
+    - hoverxref.extension
+

docs/_toc.yml

@@ -0,0 +1,18 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+parts:
+- caption: Basic examples 🪄
+  chapters:
+  - file: markdown
+  - file: notebooks
+  - file: markdown-notebooks
+- caption: Cool extensions 🕶️
+  chapters:
+  - file: intersphinx
+  - file: sphinx-examples
+  - file: sphinx-hoverxref
+  - file: sphinx-proof
+

docs/intersphinx.md

@@ -0,0 +1,28 @@
+# Intersphinx: Cross-reference other projects
+
+Behind the built-in Sphinx extension `intersphinx` is a powerful tool to reference sections in other Sphinx and Jupyter Book documentation projects.
+
+You can configure mappings to external Sphinx projects in your Jupyter Book configuration, the `_config.yml` file. In this example project, we have configured `ebp` to reference `https://executablebooks.org/en/latest/`. In the following code examples, we refer to the configured `ebp` mapping and link directly to a section called `tools`.
+
+```{tab} MyST (Markdown)
+
+```{example}
+We can link to pages in other documentation projects.
+This is a link to the
+[Executable Book project's list of tools they build](ebp:tools)
+```
+
+
+```{tab} reStructuredText
+
+```{example}
+
+```{eval-rst}
+We can link to pages in other documentation projects.
+This is a link to the
+:doc:`Executable Book project's list of tools they build <ebp:tools>`
+```
+
+```{note}
+In the above `reStructuredText` example, we use `{eval-rst}` to write reST inside a `.md` file (i.e. the one you are reading now). You only need to use this directive if you are writing reST code in a `.md` file.
+```

docs/intro.md

@@ -0,0 +1,48 @@
+(intro)=
+
+# Jupyter Book on Read the Docs
+
+This example shows a Jupyter Book project built and published on Read the Docs.
+You're encouraged to use it to get inspiration and copy & paste from the files in [the source code repository][github]. In the source repository, you will also find the relevant configuration and instructions for building Jupyter Book projects on Read the Docs.
+
+If you are using Read the Docs for the first time, have a look at the official [Read the Docs Tutorial][tutorial].
+If you are using Jupyter Book for the first time, have a look at the [official Jupyter Book documentation][jb-docs].
+
+## Why run Jupyter Book with Read the Docs?
+
+[Read the Docs](https://readthedocs.org/) simplifies developing Jupyter Book projects by automating building, versioning, and hosting of your project for you.
+You might be familiar with Read the Docs for software documentation projects, but these features are just as relevant for science.
+
+With Read the Docs, you can improve collaboration on your Jupyter Book project with Git (GitHub, GitLab, BitBucket etc.) and then connect the Git repository to Read the Docs.
+Once Read the Docs and the git repository are connected, your project will be built and published automatically every time you commit and push changes with git.
+Furthermore, if you open Pull Requests, you can preview the result as rendered by Jupyter Book.
+
+## What is in this example?
+
+Jupyter Book has a number of built-in features.
+This is a small example book to give you a feel for how book content is structured.
+It shows off a few of the major file types, as well as some sample content.
+It does not go in-depth into any particular topic - check out [the Jupyter Book documentation][jb-docs] for more information.
+
+* [Examples of Markdown](/markdown)
+* [Rendering a notebook Jupyter Notebook](/notebooks)
+* [A notebook written in MyST Markdown](/markdown-notebooks)
+
+We have also added some popular features for Jupyter Book that really you shouldn't miss when building your own project with Jupyter Book and Read the Docs:
+
+* [intersphinx to link to other documentation and Jupyter Book projects](/intersphinx)
+* [sphinx-examples to show examples and results side-by-side](/sphinx-examples)
+* [sphinx-hoverxref to preview cross-references](/sphinx-hoverxref)
+* [sphinx-proof for logic and math, to write proofs, theorems, lemmas etc.](/sphinx-proof)
+
+
+## Table of Contents
+
+Here is an automatically generated Tabel of Contents:
+
+```{tableofcontents}
+```
+
+[github]: https://github.com/readthedocs-examples/example-jupyter-book/ "GitHub source code repository for the example project"
+[tutorial]: https://docs.readthedocs.io/en/stable/tutorial/index.html "Official Read the Docs Tutorial"
+[jb-docs]: https://jupyterbook.org/en/stable/ "Official Jupyter Book documentation"

docs/logo.png

@@ -0,0 +1,54 @@
+---
+jupytext:
+  cell_metadata_filter: -all
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.11.5
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Notebooks with MyST Markdown
+
+Jupyter Book also lets you write text-based notebooks using MyST Markdown.
+See [the Notebooks with MyST Markdown documentation](https://jupyterbook.org/file-types/myst-notebooks.html) for more detailed instructions.
+This page shows off a notebook written in MyST Markdown.
+
+## An example cell
+
+With MyST Markdown, you can define code cells with a directive like so:
+
+```{code-cell}
+print(2 + 2)
+```
+
+When your book is built, the contents of any `{code-cell}` blocks will be
+executed with your default Jupyter kernel, and their outputs will be displayed
+in-line with the rest of your content.
+
+```{seealso}
+Jupyter Book uses [Jupytext](https://jupytext.readthedocs.io/en/latest/) to convert text-based files to notebooks, and can support [many other text-based notebook files](https://jupyterbook.org/file-types/jupytext.html).
+```
+
+## Create a notebook with MyST Markdown
+
+MyST Markdown notebooks are defined by two things:
+
+1. YAML metadata that is needed to understand if / how it should convert text files to notebooks (including information about the kernel needed).
+   See the YAML at the top of this page for example.
+2. The presence of `{code-cell}` directives, which will be executed with your book.
+
+That's all that is needed to get started!
+
+## Quickly add YAML metadata for MyST Notebooks
+
+If you have a markdown file and you'd like to quickly add YAML metadata to it, so that Jupyter Book will treat it as a MyST Markdown Notebook, run the following command:
+
+```
+jupyter-book myst init path/to/markdownfile.md
+```

docs/markdown-notebooks.md

@@ -0,0 +1,55 @@
+# Markdown Files
+
+Whether you write your book's content in Jupyter Notebooks (`.ipynb`) or
+in regular markdown files (`.md`), you'll write in the same flavor of markdown
+called **MyST Markdown**.
+This is a simple file to help you get started and show off some syntax.
+
+## What is MyST?
+
+MyST stands for "Markedly Structured Text". It
+is a slight variation on a flavor of markdown called "CommonMark" markdown,
+with small syntax extensions to allow you to write **roles** and **directives**
+in the Sphinx ecosystem.
+
+For more about MyST, see [the MyST Markdown Overview](https://jupyterbook.org/content/myst.html).
+
+## Sample Roles and Directives
+
+Roles and directives are two of the most powerful tools in Jupyter Book. They
+are kind of like functions, but written in a markup language. They both
+serve a similar purpose, but **roles are written in one line**, whereas
+**directives span many lines**. They both accept different kinds of inputs,
+and what they do with those inputs depends on the specific role or directive
+that is being called.
+
+Here is a "note" directive:
+
+```{note}
+Here is a note
+```
+
+It will be rendered in a special box when you build your book.
+
+Here is an inline directive to refer to a document: {doc}`markdown-notebooks`.
+
+
+## Citations
+
+You can also cite references that are stored in a `bibtex` file. For example,
+the following syntax: `` {cite}`holdgraf_evidence_2014` `` will render like
+this: {cite}`holdgraf_evidence_2014`.
+
+Moreover, you can insert a bibliography into your page with this syntax:
+The `{bibliography}` directive must be used for all the `{cite}` roles to
+render properly.
+For example, if the references for your book are stored in `references.bib`,
+then the bibliography is inserted with:
+
+```{bibliography}
+```
+
+## Learn more
+
+This is just a simple starter to get you started.
+You can learn a lot more at [jupyterbook.org](https://jupyterbook.org).