Add proposal for new Sphinx and RTD tutorials

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

@@ -17,19 +17,19 @@ Sphinx tutorial
 Appendixes are optional, i.e. not required to follow the tutorial, but
 highly recommended.
 
-0. The Sphinx way
+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.
 
-1. About this tutorial
+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.
 
-2. Getting started
+3. Getting started
 
    1. Creating our project
 
@@ -61,7 +61,7 @@ highly recommended.
       -  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
+4. First steps to document our project using Sphinx
 
    1. Converting our documentation to local HTML
 
@@ -73,23 +73,24 @@ highly recommended.
       -  Open http://localhost:8000 in a web browser, and see the HTML
          documentation (yay!)
 
-   2. Simplify documentation building by using Make [3]_
+   2. Converting our documentation to other formats
+
+      -  Install TeX (MiKTeX looks very straightforward on Windows, TeX Live
+         is an alternative)
+      -  Build PseudoXML using ``make pseudoxml``
+      - Build Text using ``make text``
+      -  See that the PDF appeared (yay!)
+
+   3. 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!)
 
-   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
+5. Customizing Sphinx configuration
 
    1. Changing the HTML theme
 
@@ -111,33 +112,110 @@ highly recommended.
       -  Rebuild the HTML docs ``make html`` and notice that now the
          times are printed (yay!)
 
-5. Writing narrative documentation with Sphinx
+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.
 
-6. Describing code in Sphinx
+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.
 
-7. Autogenerating documentation from code in Sphinx
-8. Deploying a Sphinx project online
+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
 
-9. Appendix: Using Jupyter notebooks inside Sphinx
+10. Appendix: Using Jupyter notebooks inside Sphinx
+11. 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
+----------------------
+
+1. What is Read the Docs
+2. Getting started
+
+   1. Preparing our project on GitHub
+
+      - Fork a starter GitHub repository (notice that
+        even an empty project is ready for build the first time without changes,
+        resulting in a nice "welcome to read the docs" dummy page,
+        but using something like `our demo template
+        <https://github.com/readthedocs/template>`_,
+        as a starting point
+        helps mimicking the `sphinx-quickstart` or `cookiecutter` step
+        without having to checkout the code locally)
+
+   2. Importing our project to Read the Docs
+
+      - Sign up on RTD
+      - Connect your GitHub account (is this step necessary
+        if the user signed up with GitHub?)
+      - Connect your GitHub account (to avoid manual import)
+      - Import the project (don't "Edit advanced project options", we
+        will do this later)
+      - The project is created on RTD
+      - Browse "builds", wait a couple of minutes, open the docs (yay!)
+
+   3. Basic configuration changes
+
+      - Add a description, homepage, and tags
+      - Browse other project with similar tags as yours
+        (this way we encourage tagging projects, as well as discovery)
+      - Configure your email for build failure notification
+        (until we turn them on by default)
+
+3. Improving our workflow
+
+   1. Rendering our documentation from pull requests
+
+      - 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!)
+
+   2. Using custom domains
+
+      - Essentially the steps already described in our Custom Domains reference
+
+4. 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
+
+5. 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
+
+6. 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
+
+7. Managing translations
+8. Where to go from here
+
+   - Reference our existing guides, prominent projects already using RTD,
+     our support form, our contributing documentation
+
 Possible new how-to Guides
 --------------------------