Skip to content

Latest commit

 

History

History
175 lines (128 loc) · 6.14 KB

new-sphinx-guides.rst

File metadata and controls

175 lines (128 loc) · 6.14 KB

Proposed contents for new Sphinx guides

The two main objectives are:

  • Contributing a good Sphinx tutorial for beginners. This should introduce the readers to all the various Sphinx major features in a pedagogical way, and be mostly focused on Markdown using MyST. We would try to find a place for it in the official Sphinx documentation.
  • Write a new narrative tutorial for Read the Docs that complements the existing guides and offers a cohesive story of how to use the service.

Sphinx tutorial

Appendixes are optional, i.e. not required to follow the tutorial, but highly recommended.

  1. The Sphinx way
    • Preliminary section giving an overview of what Sphinx is, how it works, how reStructuredText and Markdown/MyST are related to it, some terminology (toctree, builders), what can be done with it.
  2. About this tutorial
    • A section explaining the approach of the tutorial, as well as how to download the result of each section for closer inspection or for skipping parts of it.
  3. Getting started
    1. Creating our project
      • Present a fictitious goal for a documentation project
      • Create a blank README.md to introduce the most basic elements of Markdown (headings and paragraph text)
    2. Installing Sphinx and cookiecutter in a new development environment
      • Install Python (or miniforge)
      • Create a virtual environment (and/or conda environment)
      • Activate our virtual environment (it will always be the first step)
      • Install Sphinx inside the virtual environment
      • Check that sphinx-build --help works (yay!)
    3. Creating the documentation layout
      • Apply our cookiecutter to create a minimal docs/ directory (similar to what sphinx-quickstart does, but with source and build separation by default, project release 0.1, English language, and a MyST index, if at all) [1]
      • Check that the correct files are created (yay!)
    4. Appendix: Using version control
      • Install git (we will not use it during the tutorial)
      • Add a proper .gitignore file (copied from gitignore.io)
      • Create the first commit for the project (yay!)
  4. First steps to document our project using Sphinx
    1. Converting our documentation to local HTML
      • Create (or minimally tweak) index.md
      • Build the HTML output using sphinx-build -b -W html doc doc/_build/html [2]
      • Navigate to doc/_build/html and launch an HTTP server (python -m http.server)
      • Open http://localhost:8000 in a web browser, and see the HTML documentation (yay!)
    2. Simplify documentation building by using Make [3]
      • Install Make (nothing is needed on Windows, make.bat is standalone)
      • Add more content to index.md
      • Build HTML doing cd doc && make html
      • Observe that the HTML docs have changed (yay!)
    3. Converting our documentation to PDF
      • Install TeX (MiKTeX looks very straightforward on Windows, TeX Live is an alternative)
      • Build LaTeX using make latexpdf
      • See that the PDF appeared (yay!)
    4. Appendix: PDF without LaTeX using rinoh (beta)
  5. Customizing Sphinx configuration
    1. Changing the HTML theme
      • Install https://pypi.org/project/furo/
      • Change the html_theme in conf.py
      • Rebuild the HTML documentation and observe that the theme has changed (yay!)
    2. Changing the PDF appearance
      • Add a latex_theme and set it to howto
      • Rebuild make latexpdf
      • Check that the appearance changed (yay!)
    3. Enable an extension
      • Add a string to the extensions list in conf.py for sphinx.ext.duration
      • Rebuild the HTML docs make html and notice that now the times are printed (yay!)
  6. Writing narrative documentation with Sphinx
    • First focus on index.md, diving more into Markdown and mentioning Semantic Line Breaks.
    • Then add another .md file to teach how toctree works.
    • Then continue introducing elements of the syntax to add pictures, cross-references, and the like.
  7. Describing code in Sphinx
    • Explain the Python domain as part of narrative documentation to interleave code with text, include doctests, and justify the usefulness of the next section.
  8. Autogenerating documentation from code in Sphinx
  9. Deploying a Sphinx project online
    • A bit of background on the options: GitHub/GitLab Pages, custom server, Netlify, Read the Docs
    • Make reference to Read the Docs tutorial
  10. Appendix: Using Jupyter notebooks inside Sphinx

Possible new how-to Guides

Some ideas for extra guides on specific topics, still for beginners but more problem-oriented documents, covering a wide range of use cases:

  • How to turn a bunch of Markdown files into a Sphinx project
  • How to turn a bunch of Jupyter notebooks into a Sphinx project
  • How to localize an existing Sphinx project
  • How to customize the appearance of the HTML output of a Sphinx project
  • How to convert existing reStructuredText documentation to Markdown
  • How to use Doxygen autogenerated documentation inside a Sphinx project
  • How to keep a changelog of your project

Reference

All the references should be external: the Sphinx reference, the MyST and reST syntax specs, and so forth.

[1]Similar to https://github.com/sphinx-contrib/cookiecutter, but only for the docs/ directory? This way it can be less opinionated about everything else
[2]At first I considered “make mode”, but the current maintainers don’t know much about its original intent (see my comment here and the discussion after it)
[3]There have been attempts at creating a sphinx command, see this pull request