Skip to content

Commit 67d5d39

Browse files
committed
starting docs with jupyter book and sphinx
1 parent c4c9f57 commit 67d5d39

16 files changed

+603
-0
lines changed

.github/workflows/documentation.yml

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# https://stackoverflow.com/a/58008902
2+
release_sphinx:
3+
needs: [build]
4+
runs-on: ubuntu-latest
5+
container:
6+
image: python:3.6
7+
volumes:
8+
- dist:dist
9+
- public:public
10+
steps:
11+
12+
# check out sources that will be used for autodocs, plus readme
13+
- uses: actions/checkout@v1
14+
15+
# download wheel that was build and uploaded in the build step
16+
- uses: actions/download-artifact@v1
17+
with:
18+
name: distributions
19+
path: dist
20+
21+
# didn't need to change anything here, but had to add sphinx.ext.githubpages
22+
# to my conf.py extensions list. that fixes the broken uploads
23+
- name: Building documentation
24+
run: |
25+
pip install dist/*.whl
26+
pip install sphinx Pallets-Sphinx-Themes
27+
sphinx-apidoc --no-toc --module-first -o docs/autodoc src/stenotype
28+
sphinx-build docs public -b dirhtml
29+
30+
# # still need to build and set the PAT to get a rebuild on the pages job,
31+
# # apart from that quite clean and nice
32+
# - name: github pages deploy
33+
# uses: peaceiris/actions-gh-pages@v2.3.1
34+
# env:
35+
# PERSONAL_TOKEN: ${{ secrets.PAT }}
36+
# PUBLISH_BRANCH: gh-pages
37+
# PUBLISH_DIR: public
38+
39+
# # # since gh-pages has a history, this step might no longer be necessary.
40+
# # - uses: actions/upload-artifact@v1
41+
# # with:
42+
# # name: documentation
43+
# # path: public

.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,3 +118,5 @@ venv/
118118
venv_test/
119119

120120
sandbox.py
121+
122+
docs/_build

docs/README.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# How to Docs
2+
3+
## Building the Docs
4+
5+
```
6+
# go repo root folder
7+
cd NavAbilitySDK.py
8+
9+
# Install required Python dependencies (Sphinx etc.)
10+
pip install -r docs/requirements.txt
11+
12+
# Run Jupyter Book
13+
jupyter-book build docs/
14+
15+
# View the docs with for instance firefox
16+
firefox docs/_build/index.html
17+
```
18+
19+
## Resources
20+
21+
This documentation folder is based on work from:
22+
- https://github.com/readthedocs-examples/example-jupyter-book
23+
24+
With auto docstring extension:
25+
- https://jupyterbook.org/en/stable/advanced/developers.html?highlight=docstrings#api-reference-from-docstrings
26+
27+

docs/_config.yml

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Book settings
2+
# Learn more at https://jupyterbook.org/customize/config.html
3+
# Comprehensive example: https://github.com/executablebooks/jupyter-book/blob/master/docs/_config.yml
4+
5+
title: Example Jupyter Book for Read the Docs
6+
author: Read the Docs team
7+
logo: logo.png
8+
9+
# Force re-execution of notebooks on each build.
10+
# See https://jupyterbook.org/content/execute.html
11+
execute:
12+
execute_notebooks: force
13+
14+
# Define the name of the latex output file for PDF builds
15+
latex:
16+
latex_documents:
17+
targetname: book.tex
18+
19+
# Add a bibtex file so that we can create citations
20+
bibtex_bibfiles:
21+
- references.bib
22+
23+
# Information about where the book exists on the web
24+
repository:
25+
url: https://github.com/readthedocs-examples/example-jupyter-book # Online location of your book
26+
path_to_book: docs # Optional path to your book, relative to the repository root
27+
branch: main # Which branch of the repository should be used when creating links (optional)
28+
29+
# Add GitHub buttons to your book
30+
# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
31+
html:
32+
use_issues_button: true
33+
use_repository_button: true
34+
35+
sphinx:
36+
config:
37+
intersphinx_mapping:
38+
ebp:
39+
- "https://executablebooks.org/en/latest/"
40+
- null
41+
myst-parser:
42+
- "https://myst-parser.readthedocs.io/en/latest/"
43+
- null
44+
myst-nb:
45+
- "https://myst-nb.readthedocs.io/en/latest/"
46+
- null
47+
sphinx:
48+
- "https://www.sphinx-doc.org/en/master"
49+
- null
50+
nbformat:
51+
- "https://nbformat.readthedocs.io/en/latest"
52+
- null
53+
sd:
54+
- "https://sphinx-design.readthedocs.io/en/latest"
55+
- null
56+
sphinxproof:
57+
- "https://sphinx-proof.readthedocs.io/en/latest/"
58+
- null
59+
hoverxref_intersphinx:
60+
- "sphinxproof"
61+
mathjax3_config:
62+
tex:
63+
macros:
64+
"N": "\\mathbb{N}"
65+
"floor": ["\\lfloor#1\\rfloor", 1]
66+
"bmat": ["\\left[\\begin{array}"]
67+
"emat": ["\\end{array}\\right]"]
68+
69+
extra_extensions:
70+
- sphinx.ext.intersphinx
71+
- sphinx.ext.autodoc
72+
- sphinx_inline_tabs
73+
- sphinx_proof
74+
- sphinx_examples
75+
- hoverxref.extension
76+

docs/_toc.yml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Table of contents
2+
# Learn more at https://jupyterbook.org/customize/toc.html
3+
4+
format: jb-book
5+
root: intro
6+
parts:
7+
- caption: Basic examples 🪄
8+
chapters:
9+
- file: markdown
10+
- file: notebooks
11+
- file: markdown-notebooks
12+
- caption: Cool extensions 🕶️
13+
chapters:
14+
- file: intersphinx
15+
- file: sphinx-examples
16+
- file: sphinx-hoverxref
17+
- file: sphinx-proof
18+

docs/intersphinx.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Intersphinx: Cross-reference other projects
2+
3+
Behind the built-in Sphinx extension `intersphinx` is a powerful tool to reference sections in other Sphinx and Jupyter Book documentation projects.
4+
5+
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`.
6+
7+
```{tab} MyST (Markdown)
8+
9+
```{example}
10+
We can link to pages in other documentation projects.
11+
This is a link to the
12+
[Executable Book project's list of tools they build](ebp:tools)
13+
```
14+
15+
16+
```{tab} reStructuredText
17+
18+
```{example}
19+
20+
```{eval-rst}
21+
We can link to pages in other documentation projects.
22+
This is a link to the
23+
:doc:`Executable Book project's list of tools they build <ebp:tools>`
24+
```
25+
26+
```{note}
27+
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.
28+
```

docs/intro.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
(intro)=
2+
3+
# Jupyter Book on Read the Docs
4+
5+
This example shows a Jupyter Book project built and published on Read the Docs.
6+
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.
7+
8+
If you are using Read the Docs for the first time, have a look at the official [Read the Docs Tutorial][tutorial].
9+
If you are using Jupyter Book for the first time, have a look at the [official Jupyter Book documentation][jb-docs].
10+
11+
## Why run Jupyter Book with Read the Docs?
12+
13+
[Read the Docs](https://readthedocs.org/) simplifies developing Jupyter Book projects by automating building, versioning, and hosting of your project for you.
14+
You might be familiar with Read the Docs for software documentation projects, but these features are just as relevant for science.
15+
16+
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.
17+
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.
18+
Furthermore, if you open Pull Requests, you can preview the result as rendered by Jupyter Book.
19+
20+
## What is in this example?
21+
22+
Jupyter Book has a number of built-in features.
23+
This is a small example book to give you a feel for how book content is structured.
24+
It shows off a few of the major file types, as well as some sample content.
25+
It does not go in-depth into any particular topic - check out [the Jupyter Book documentation][jb-docs] for more information.
26+
27+
* [Examples of Markdown](/markdown)
28+
* [Rendering a notebook Jupyter Notebook](/notebooks)
29+
* [A notebook written in MyST Markdown](/markdown-notebooks)
30+
31+
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:
32+
33+
* [intersphinx to link to other documentation and Jupyter Book projects](/intersphinx)
34+
* [sphinx-examples to show examples and results side-by-side](/sphinx-examples)
35+
* [sphinx-hoverxref to preview cross-references](/sphinx-hoverxref)
36+
* [sphinx-proof for logic and math, to write proofs, theorems, lemmas etc.](/sphinx-proof)
37+
38+
39+
## Table of Contents
40+
41+
Here is an automatically generated Tabel of Contents:
42+
43+
```{tableofcontents}
44+
```
45+
46+
[github]: https://github.com/readthedocs-examples/example-jupyter-book/ "GitHub source code repository for the example project"
47+
[tutorial]: https://docs.readthedocs.io/en/stable/tutorial/index.html "Official Read the Docs Tutorial"
48+
[jb-docs]: https://jupyterbook.org/en/stable/ "Official Jupyter Book documentation"

docs/logo.png

9.62 KB
Loading

docs/markdown-notebooks.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
jupytext:
3+
cell_metadata_filter: -all
4+
formats: md:myst
5+
text_representation:
6+
extension: .md
7+
format_name: myst
8+
format_version: 0.13
9+
jupytext_version: 1.11.5
10+
kernelspec:
11+
display_name: Python 3
12+
language: python
13+
name: python3
14+
---
15+
16+
# Notebooks with MyST Markdown
17+
18+
Jupyter Book also lets you write text-based notebooks using MyST Markdown.
19+
See [the Notebooks with MyST Markdown documentation](https://jupyterbook.org/file-types/myst-notebooks.html) for more detailed instructions.
20+
This page shows off a notebook written in MyST Markdown.
21+
22+
## An example cell
23+
24+
With MyST Markdown, you can define code cells with a directive like so:
25+
26+
```{code-cell}
27+
print(2 + 2)
28+
```
29+
30+
When your book is built, the contents of any `{code-cell}` blocks will be
31+
executed with your default Jupyter kernel, and their outputs will be displayed
32+
in-line with the rest of your content.
33+
34+
```{seealso}
35+
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).
36+
```
37+
38+
## Create a notebook with MyST Markdown
39+
40+
MyST Markdown notebooks are defined by two things:
41+
42+
1. YAML metadata that is needed to understand if / how it should convert text files to notebooks (including information about the kernel needed).
43+
See the YAML at the top of this page for example.
44+
2. The presence of `{code-cell}` directives, which will be executed with your book.
45+
46+
That's all that is needed to get started!
47+
48+
## Quickly add YAML metadata for MyST Notebooks
49+
50+
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:
51+
52+
```
53+
jupyter-book myst init path/to/markdownfile.md
54+
```

docs/markdown.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Markdown Files
2+
3+
Whether you write your book's content in Jupyter Notebooks (`.ipynb`) or
4+
in regular markdown files (`.md`), you'll write in the same flavor of markdown
5+
called **MyST Markdown**.
6+
This is a simple file to help you get started and show off some syntax.
7+
8+
## What is MyST?
9+
10+
MyST stands for "Markedly Structured Text". It
11+
is a slight variation on a flavor of markdown called "CommonMark" markdown,
12+
with small syntax extensions to allow you to write **roles** and **directives**
13+
in the Sphinx ecosystem.
14+
15+
For more about MyST, see [the MyST Markdown Overview](https://jupyterbook.org/content/myst.html).
16+
17+
## Sample Roles and Directives
18+
19+
Roles and directives are two of the most powerful tools in Jupyter Book. They
20+
are kind of like functions, but written in a markup language. They both
21+
serve a similar purpose, but **roles are written in one line**, whereas
22+
**directives span many lines**. They both accept different kinds of inputs,
23+
and what they do with those inputs depends on the specific role or directive
24+
that is being called.
25+
26+
Here is a "note" directive:
27+
28+
```{note}
29+
Here is a note
30+
```
31+
32+
It will be rendered in a special box when you build your book.
33+
34+
Here is an inline directive to refer to a document: {doc}`markdown-notebooks`.
35+
36+
37+
## Citations
38+
39+
You can also cite references that are stored in a `bibtex` file. For example,
40+
the following syntax: `` {cite}`holdgraf_evidence_2014` `` will render like
41+
this: {cite}`holdgraf_evidence_2014`.
42+
43+
Moreover, you can insert a bibliography into your page with this syntax:
44+
The `{bibliography}` directive must be used for all the `{cite}` roles to
45+
render properly.
46+
For example, if the references for your book are stored in `references.bib`,
47+
then the bibliography is inserted with:
48+
49+
```{bibliography}
50+
```
51+
52+
## Learn more
53+
54+
This is just a simple starter to get you started.
55+
You can learn a lot more at [jupyterbook.org](https://jupyterbook.org).

0 commit comments

Comments
 (0)