Add proposal for new Sphinx and RTD tutorials

docs/development/design/new-sphinx-guides.rst

@@ -0,0 +1,175 @@
+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.
+
+0. 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.
+
+1. 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.
+
+2. 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!)
+
+3. 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)
+
+4. 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!)
+
+5. 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.
+
+6. 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.
+
+7. Autogenerating documentation from code in Sphinx
+8. 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
+
+9. Appendix: Using Jupyter notebooks inside Sphinx
+
+.. note 
+
+   - Looks like MathJax is enabled by default now? Can't see a reference in the docstrings
+
+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 <https://github.com/sphinx-doc/sphinx/issues/3196#issuecomment-819529513>`__
+   and the discussion after it)
+.. [3]
+   There have been attempts at creating a `sphinx` command, see
+   `this pull request <https://github.com/sphinx-doc/sphinx/pull/6938/>`__