Add proposal for new Sphinx and RTD tutorials

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

@@ -1,102 +1,95 @@
 Proposed contents for new Sphinx guides
 =======================================
 
-This classification follows the `Diátaxis Framework <https://diataxis.fr/>`__.
+The two main objectives are:
 
-Tutorial
---------
+- 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.
 
-   **Objective**: Write a tutorial, some examples, and reference
-   documentation for our Python code.
-
-Every step should lead to a “yay!” moment, which marks the end of the
-section. This keeps the learner motivated.
+Sphinx tutorial
+---------------
 
 Appendixes are optional, i.e. not required to follow the tutorial, but
 highly recommended.
 
-1. Getting started
+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
 
-   1. Creating our code project
+   -  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.
 
-      -  What is our library (present some minimal ``x.py`` file in a
-         dedicated directory, will be the basis of the tutorial)
-      -  Install Python
-      -  Check that our code works (yay!)
+2. Getting started
 
-   2. Using virtual environments for development
+   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)
-      -  Check that our code also works (yay!)
+      -  Install Sphinx inside the virtual environment
+      -  Check that ``sphinx-build --help`` works (yay!)
 
-   3. Adding external dependencies
+   3. Creating the documentation layout
 
-      -  Add import from small third party library
-      -  Install it inside our virtual environment
-      -  Check that our code works (yay!) and it doesn’t outside the
-         virtual environment (as expected)
+      -  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 use it during the tutorial)
-      -  Write a barebones ``README.md`` (we will expand it later), a
-         ``.gitignore`` file (copied from gitignore.io), and a proper
-         ``LICENSE`` file
-
-         -  ``LICENSE.md``? ``LICENSE``? ``COPYING``? Whatever
-
+      -  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!)
 
-2. First steps to document our project using Sphinx
-
-   1. Installing Sphinx
-
-      -  Activate our virtual environment
-      -  Install Sphinx inside the virtual environment
-      -  Check that ``sphinx-build --help`` works (yay!)
-
-   2. Creating the project layout
+3. First steps to document our project using Sphinx
 
-      -  Run the sphinx-quickstart wizard: separate source and build
-         (``y``), project name, author name, and go
-      -  Check that the correct files are created (yay!)
-
-   3. Converting our documentation to local HTML
+   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``  [1]_
+         ``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!)
 
-   4. Making a change and regenerating the documentation
-
-      -  Add a sentence to ``index.rst`` (no need to explain in detail
-         what reST is at this stage)
-      -  Rebuild HTML ``sphinx-build -W -b html ...``
-      -  Observe that the HTML docs have changed (yay!) (we will have to
-         do this every time we change something)
+   2. Simplify documentation building by using Make [3]_
 
-   5. Simplify documentation building by using Make
-
-      -  Install Make (and its Windows counterpart)
-      -  Make another trivial change
+      -  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!)
 
-   6. Converting our documentation to PDF
+   3. Converting our documentation to PDF
 
-      -  Install TeX Live to create PDF output (should work on every
-         operative system)
+      -  Install TeX (MiKTeX looks very straightforward on Windows, TeX Live
+         is an alternative)
       -  Build LaTeX using ``make latexpdf``
       -  See that the PDF appeared (yay!)
 
-   7. Appendix: PDF without LaTeX using rinoh (beta)
+   4. Appendix: PDF without LaTeX using rinoh (beta)
 
-3. Customizing Sphinx configuration
+4. Customizing Sphinx configuration
 
    1. Changing the HTML theme
 
@@ -118,42 +111,40 @@ highly recommended.
       -  Rebuild the HTML docs ``make html`` and notice that now the
          times are printed (yay!)
 
-4. Writing narrative documentation with Sphinx
+5. Writing narrative documentation with Sphinx
 
-   -  First focus on ``index.rst``, gently introducing the learner to
-      reST and mentioning Semantic Line Breaks.
-   -  Then add another ``.rst`` file to teach how ``toctree`` works.
-   -  Then enable Markdown adding ``myst_parser`` to the extensions and
-      authoring a Markdown file, to show that both can exist at the same
-      time.
+   -  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.
 
-5. Using Jupyter notebooks inside Sphinx
 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
-   - The fact that the ``index.rst`` created by ``sphinx-quickstart`` is written in
-     reStructuredText gets in the way of teaching Markdown (MyST).
-     On the other hand, users need to know reST anyway to write Python docstrings,
-     so it is necessary to teach both.
 
-How-to Guides
--------------
+Possible new how-to Guides
+--------------------------
 
-Practical, problem-oriented documents, more open ended than the
-tutorial. For example:
+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 publish (deploy) a Sphinx project
--  How to publish (deploy) the documentation of a Python library to PyPI
 -  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
@@ -164,23 +155,21 @@ tutorial. For example:
    project
 -  How to keep a changelog of your project
 
-Background
-----------
-
-More detailed explanations of certain topics. For example:
-
--  Understanding reStructuredText in Sphinx
--  What to put in ``conf.py``
--  Sphinx internals
-
 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/>`__