diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst new file mode 100644 index 00000000000..71ed2566116 --- /dev/null +++ b/docs/development/design/new-sphinx-guides.rst @@ -0,0 +1,243 @@ +Proposed contents for new Sphinx guides +======================================= + +.. note:: + + This work is in progress, see discussion on `this Sphinx + issue `_ + and the pull requests linked at the end. + +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. + +#. 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. + +#. 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. + +#. Getting started + + #. 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) + + #. 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!) + + #. 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!) + + #. 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!) + +#. First steps to document our project using Sphinx + + #. 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!) + + #. Converting our documentation to other formats + + - Build PseudoXML using ``make pseudoxml`` + - Build Text using ``make text`` + - See how the various formats change the output (yay!) + + #. Appendix: 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!) + + #. Appendix: PDF without LaTeX using rinoh (beta) + +#. Customizing Sphinx configuration + + #. 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!) + + #. Changing the PDF appearance + + - Add a ``latex_theme`` and set it to ``howto`` + - Rebuild ``make latexpdf`` + - Check that the appearance changed (yay!) + + #. 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!) + +#. 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. + +#. 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. + +#. Autogenerating documentation from code in Sphinx +#. 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 + +#. Appendix: Using Jupyter notebooks inside Sphinx +#. Appendix: Understanding the docutils document tree +#. Appendix: Where to go from here + + - Refer the user to the Sphinx, reST and MyST references, + prominent projects already using Sphinx, + compilations of themes and extensions, + the development documentation. + +.. note + + - Looks like MathJax is enabled by default now? Can't see a reference in the docstrings + +Read the Docs tutorial +---------------------- + +#. The Read the Docs way +#. Getting started + + #. Preparing our project on GitHub + + - Fork a starter GitHub repository (something like `our demo template + `_, + as a starting point that + helps mimicking the `sphinx-quickstart` or `cookiecutter` step + without having to checkout the code locally) + + #. Importing our project to Read the Docs + + - Sign up with GitHub on RTD + - Import the project (don't "Edit advanced project options", we + will do this later) + - The project is created on RTD + - Browse "builds", open the build live logs, wait a couple of minutes, + open the docs (yay!) + + #. Basic configuration changes + + - Add a description, homepage, and tags + - Configure your email for build failure notification + (until we turn them on by default) + - Enable "build pull requests for this project" in the advanced settings + - Edit a file from the GitHub UI as part of a new branch, and open a pull request + - See the RTD check on the GitHub PR UI, wait a few minutes, open result (yay!) + +#. Customizing the build process + + - Use `.readthedocs.yaml` (rather than the web UI) to customize build formats, + change build requirements and Python version, enable fail-on-warnings + +#. Versioning documentation + + - Explain how to manage versions on RTD: create release branches, + activate the corresponding version, browse them in the version selector, + selectively build versions + - Intermediate topics: hide versions, create Automation Rules + +#. Getting insights from your projects + + - Move around the project, explore results in Traffic Analytics + - Play around with server-side search, explore results in Search Analytics + +#. Managing translations + +#. Where to go from here + + - Reference our existing guides, prominent projects already using RTD, + domain configuration, our support form, our contributing documentation + +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 `__