{ "cells": [ { "cell_type": "markdown", "id": "recreational-ensemble", "metadata": {}, "source": [ "# Sphinx Documentation Tutorial\n", "\n", "Notes from 11-Mar-2021 Sphinx documentation tutorial for MOAD group members.\n", "\n", "`environment.yaml` is a conda environment description that includes the packages discussed in the tutorial" ] }, { "cell_type": "markdown", "id": "changing-sword", "metadata": {}, "source": [ "## Outline\n", "\n", "* Key concept: text processing in contrast to word processor software\n", "* Sphinx docs tools and pipeline\n", "* reStructuredText syntax\n", "* Sphinx roles and directives" ] }, { "cell_type": "markdown", "id": "latest-ireland", "metadata": {}, "source": [ "## References\n", "\n", "* MOAD docs about using Sphinx:\n", " https://ubc-moad-docs.readthedocs.io/en/latest/sphinx_docs.html\n", "* Sphinx docs, official and detailed:\n", " https://www.sphinx-doc.org/en/master/\n", "* Eric Holscher's Sphinx and Read the Docs tutorial, a little old, but includes a great reStructuredText cheat sheet:\n", " https://sphinx-tutorial.readthedocs.io/\n", "* Chris Holdgraf's Zero to Docs tutorial, less complete than Eric's, but a different take:\n", " https://docathon.github.io/zero_to_docs/index.html\n", "\n", "\n", "* Docs for `nbsphinx` extension to parser Jupyter Notebooks into pages in Sphinx docs:\n", " https://nbsphinx.readthedocs.io/en/0.8.2/\n", "\n", "\n", "* Docs for MyST parser that using extended Markdown syntax in Sphinx, new-ish, not enabled in any of our docs repositories (yet?):\n", " https://myst-parser.readthedocs.io/en/latest/index.html" ] }, { "cell_type": "markdown", "id": "corporate-processing", "metadata": {}, "source": [ "## Tools and Pipeline\n", "\n", "* Edit text\n", "* run Sphinx (`make html`)\n", "* Preview in browser (`firefox _build/html/index.html`)\n", "* `git add` and `git commit`\n", "* `git push` to GitHub\n", "* GitHub Action linkcheck (some repos) (`make linkcheck`)\n", "* GitHub sends webhook signal to ReadtheDocs\n", "* ReadtheDocs does `git pull` and `make html` (and some other stuff)\n", "* ReadtheDocs puts HTML on web at `something.readthedocs.io`" ] }, { "cell_type": "markdown", "id": "quiet-valley", "metadata": {}, "source": [ "## reStructuredText (rST) Syntax\n", "\n", "Sphinx docs about rST: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html\n", "\n", "### Directories, `index.rst` Files & TOC Trees\n", "* directories are sections of docs\n", "* `index.rst` files in each directory contain `toctree` directives that contain\n", " lists of `.rst` (and perhaps `.ipynb`) files that the pages of the section\n", "\n", "### Headings\n", "* headings are underlines\n", "* different underline characters for different heading levels\n", "* underlines must be at least as long as the heading text; shorter is an error; longer is okay but messy\n", "* our convention:\n", " * `***` above and below for top (1st) level heading\n", " * `===` below for 2nd level heading\n", " * `---` below for 3rd level heading\n", " * `~~~` below for 4th level heading\n", " * do you really need a 5th+ level headings?\n", "\n", "### Inline Markup\n", "* `*foo*` for *emphasis*; usually renders as italicized\n", "* `**foo**` for **bold**\n", "* ` ``foo`` ` for special literal highlighting, but consider using a semantic role (below) instead\n", "\n", "### Bullet and Enumerated Lists\n", "* `*` or `-` for bullet (aka unordered) lists; need to indent if list item is >1 line long\n", "* `1.`, `2.`, or `a.`, `b.` for enumerated lists; `#.` does automatic numbering\n" ] }, { "cell_type": "markdown", "id": "exempt-friday", "metadata": {}, "source": [ "## Sphinx Roles & Directives" ] }, { "cell_type": "markdown", "id": "rotary-architect", "metadata": {}, "source": [ "Sphinx docs about roles: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html\n", "\n", "Sphinx docs about directives: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html\n", "\n", "Sorry for so few examples here.\n", "The different meanings of backticks (\\`) in Markdown and rST make it difficult to write examples of one in the other.\n", "\n", "### Super-scripts and sub-scripts\n", "* `:sup:`, `:sub:`\n", "\n", "### Cross-references and External Links\n", "* `:ref:`\n", "* See https://ubc-moad-docs.readthedocs.io/en/latest/sphinx_docs.html#links-and-cross-references\n", "\n", "### Math Using LaTeX Syntax\n", "* `:math:` role for inline math\n", "* `.. math::` directive for display math\n", "\n", "### Semantic Roles\n", "Here are a few of the ones commonly used in our docs.\n", "There are more in the Sphinx docs.\n", "* `:command:` for operating system level commands;\n", " e.g. `rm`, `ssh --N -L 4343:salish:8888 salish`\n", "* `:kbd:` for a series of keystrokes; renders in a monospace font\n", " I often (ab)use this for host names and the like that don't fall\n", " into another semantic category\n", "* `:file:` for directory or file names\n", "* `:guilabel:` for graphical user interface (GUI) elements like buttons\n", "* `:menuselection:` for sequences of GUI menu selections\n", "* `:program:` for the names of programs like `Matlab` or `Word`\n", "\n", "### Table of Contents\n", "* `.. toctree::` every `index.rst` file needs one\n", "\n", "### Code Blocks\n", "* `.. code-block::` for syntax highlighted code in many, many languages\n", " (the [list of languages that can be handled](https://pygments.org/docs/lexers/#lexers-for-python-and-related-languages) is astonishing\n", " \n", "### Pre-formatted Text\n", "For terminal output, for example.\n", "* `::` at the end of a line, or on a line by itself\n", " displays the following indented text as literal text in a monospace font\n", "* `.. code-block:: text` can be used as a more explicit alternative to `::`\n", " on a line by itself" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.2" } }, "nbformat": 4, "nbformat_minor": 5 }