Sphinx docs and Github Pages

[Mathijs995]

Nocturne Sphinx documentation & docs on Github pages

New

1. Sphinx docs using https://sphinx-book-theme.readthedocs.io/en/stable/index.html
2. Base documentation skeleton including tutorials, contribution guidelines, and API reference
3. pre-commit notebook quality checks and jupytext support for notebooks
4. Host Sphinx docs via Github Pages using the new Github workflow Build Sphinx docs and deploy to GH Pages

Note: Python dependencies have been updated and in order to run the code, you need to install the developer requirements from ./requirements.dev.txt. To do this, run pip install -r requirements.dev.txt.

Test PR

1. Review code in different commits. Note: Commits are structured in a way that you can decide what to include and what not to include
2. Test environment setup by creating a fresh environment Python 3.8 and validating that the following commands succeed without errors and the code base can be used afterward.

pip install -r ./requirements.txt
pip install -r ./requirements.dev.txt
pip install -e .

3. Locally create and review the Sphinx docs - instructions below
4. Deploy Sphinx docs using Github Pages - instructions below

Build and view Sphinx docs locally

1. Build documentation by running sphinx-build -b html ./docs/source /docs/build/html
2. View the documentation by opening the file ./docs/build/html/index.html in the browser. When a browser is configured in your terminal window and HTML files are by default opened by the browser, you can run open ./docs/build/html/index.html

Host Sphinx docs using GitHub Pages

1. Go to https://github.com/$USER/nocturne/settings/pages
2. In the “Source” section, choose “Github Actions” in the dropdown menu
3. Go to https://github.com/$USER/nocturne/actions and manually start the workflow Build Sphinx docs and deploy to GH Pages
4. Verify the website is online (could take up to 10 minutes to be only) by visiting: https://$USER.github.io/nocturne/

TODO

Urgent

• Refer to documentation from README and in the repo description
• Documentation contributing instructions (https://sphinx-book-theme.readthedocs.io/en/stable/tutorials/get-started.html)
• Notebook workflow instructions, i.e., add in README or in another separate file how to work with jupytext and whether to track both ipynb and md versions of notebooks
• Clean up and extend Sphinx documentation

Decisions to be made

• Whether to use Sphinx docs
• Whether to use Github Pages or another platform to host docs
• What notebook workflow should look like, how to incorporate jupytext and what files to track on git (e.g. notebook & md, notebook only or md only)

Backlog

• Move tutorial data from docs to data directory
• The toctree on the landing page differs from the toctree on the other pages in the Sphinx documentation
• Choose logo and update it
• Add flaticon
• Add API reference for code base

[daphne-cornelisse]

Git workflow with Jupytext

• Initial problem: Editing Jupyter Notebooks with multiple users in git is messy and it gets hard to track changes.
• Proposed solution:
  • Use Jupytext to convert the .ipynb files to .md files
    • Use the option Pair Notebook with Markdown to create a synced markdown copy of your notebook. The markdown file contains all of the input cells in a format that is easy to read and is updated each time we save the notebook file.
      • ( + ) No merge conflicts
      • ( + ) Can apply flake8, black, isort etc.
      • ( + ) Convenient editing
    • Current problems:
      • Output of .md files is not rendered in Jupyter (Only works in Jupyter lab)
      • To build documentation we need .ipynb files (See this discussion How to build a documentation site with Jupytext? mwouts/jupytext#247
    • Proposed solutions:
      • 1. Keep two copies of every tutorial: both a rendered ipynb format and a markdown format. Use the markdown formats for reviewing and the other one for creating the docs.
      • 2. ... #TODO
      • 3. ... #TODO