From 1f2c6d5c9b06a811ff19ba42b28faec8381cf661 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Wed, 14 Apr 2021 20:53:43 +0200 Subject: [PATCH 01/21] Add proposal for new Sphinx guides --- docs/development/design/new-sphinx-guides.rst | 186 ++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 docs/development/design/new-sphinx-guides.rst diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst new file mode 100644 index 00000000000..cf0efd87000 --- /dev/null +++ b/docs/development/design/new-sphinx-guides.rst @@ -0,0 +1,186 @@ +Proposed contents for new Sphinx guides +======================================= + +This classification follows the `Diátaxis Framework `__. + +Tutorial +-------- + + **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. + +Appendixes are optional, i.e. not required to follow the tutorial, but +highly recommended. + +1. Getting started + + 1. Creating our code project + + - 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. Using virtual environments for development + + - 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!) + + 3. Adding external dependencies + + - 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) + + 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 + + - 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 + + - 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 + + - Build the HTML output using + ``sphinx-build -b -W html doc doc/_build/html`` [1]_ + - 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) + + 5. Simplify documentation building by using Make + + - Install Make (and its Windows counterpart) + - Make another trivial change + - Build HTML doing ``cd doc && make html`` + - Observe that the HTML docs have changed (yay!) + + 6. Converting our documentation to PDF + + - Install TeX Live to create PDF output (should work on every + operative system) + - Build LaTeX using ``make latexpdf`` + - See that the PDF appeared (yay!) + + 7. Appendix: PDF without LaTeX using rinoh (beta) + +3. 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!) + +4. 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. + - 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 + +.. 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 +------------- + +Practical, problem-oriented documents, more open ended than the +tutorial. For example: + +- 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 +- 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 + +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] + 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) From c578cc69cbc44ff404b3356872a42bf55359cd10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Wed, 21 Apr 2021 01:00:07 +0200 Subject: [PATCH 02/21] Update proposal for Sphinx tutorial --- docs/development/design/new-sphinx-guides.rst | 153 ++++++++---------- 1 file changed, 69 insertions(+), 84 deletions(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index cf0efd87000..a459f3a95e9 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -1,102 +1,95 @@ Proposed contents for new Sphinx guides ======================================= -This classification follows the `Diátaxis Framework `__. +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 +3. First steps to document our project using Sphinx - - Activate our virtual environment - - Install Sphinx inside the virtual environment - - Check that ``sphinx-build --help`` works (yay!) - - 2. Creating the project layout - - - 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 + 2. Simplify documentation building by using Make [3]_ - - 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) - - 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,18 +111,14 @@ 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 @@ -137,20 +126,18 @@ highly recommended. usefulness of the next section. 7. Autogenerating documentation from code in Sphinx +8. 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 @@ -164,15 +151,6 @@ 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 --------- @@ -180,7 +158,14 @@ 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 `__ From 413904004d885ac91f25b64491999cc93afb90f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Wed, 21 Apr 2021 01:05:42 +0200 Subject: [PATCH 03/21] Make deployment part of the Sphinx tutorial --- docs/development/design/new-sphinx-guides.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index a459f3a95e9..5676ecd597f 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -126,7 +126,13 @@ highly recommended. usefulness of the next section. 7. Autogenerating documentation from code in Sphinx -8. Appendix: Using Jupyter notebooks inside 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 @@ -139,8 +145,6 @@ 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 From ca9d323a53df796a58160ba9432ffc16288d4941 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 19:02:44 +0200 Subject: [PATCH 04/21] Use simpler formats instead of PDF Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/development/design/new-sphinx-guides.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index 5676ecd597f..fec978f1251 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -80,11 +80,12 @@ highly recommended. - Build HTML doing ``cd doc && make html`` - Observe that the HTML docs have changed (yay!) - 3. Converting our documentation to PDF + 3. Converting our documentation to other formats - Install TeX (MiKTeX looks very straightforward on Windows, TeX Live is an alternative) - - Build LaTeX using ``make latexpdf`` + - Build PseudoXML using ``make pseudoxml`` + - Build Text using ``make text`` - See that the PDF appeared (yay!) 4. Appendix: PDF without LaTeX using rinoh (beta) From 8967b1c956129d48d928aa1dde1ba1738c6affa2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 19:07:41 +0200 Subject: [PATCH 05/21] Move "Make" mode to appendix --- docs/development/design/new-sphinx-guides.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index fec978f1251..3e35ba0a501 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -73,14 +73,7 @@ highly recommended. - 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 other formats + 2. Converting our documentation to other formats - Install TeX (MiKTeX looks very straightforward on Windows, TeX Live is an alternative) @@ -88,6 +81,13 @@ highly recommended. - 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!) + 4. Appendix: PDF without LaTeX using rinoh (beta) 4. Customizing Sphinx configuration From 044d9c84515b9b6601b366efff53df2991b43c06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 19:43:11 +0200 Subject: [PATCH 06/21] Add final "where to go from here" appendix for Sphinx --- docs/development/design/new-sphinx-guides.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index 3e35ba0a501..8b54f2b75c2 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -134,6 +134,12 @@ highly recommended. - Make reference to Read the Docs tutorial 9. Appendix: Using Jupyter notebooks inside Sphinx +10. 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 From c4a5e6b64f8151fee918731a0b225b62a3f32a0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 19:43:38 +0200 Subject: [PATCH 07/21] Add proposal for Read the Docs tutorial --- docs/development/design/new-sphinx-guides.rst | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index 8b54f2b75c2..967f25f0250 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -145,6 +145,77 @@ highly recommended. - Looks like MathJax is enabled by default now? Can't see a reference in the docstrings +Read the Docs tutorial +---------------------- + +0. What is Read the Docs +1. 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 + `_, + 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) + +2. 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 + +3. 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 + +4. 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 + +5. 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 + +6. Managing translations +7. 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 -------------------------- From 94fff523b287a0d9858e7a4d51682f16fdf6230c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 19:46:13 +0200 Subject: [PATCH 08/21] Obey linter --- docs/development/design/new-sphinx-guides.rst | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index 967f25f0250..ba04c5953c4 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/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 @@ -90,7 +90,7 @@ highly recommended. 4. Appendix: PDF without LaTeX using rinoh (beta) -4. Customizing Sphinx configuration +5. Customizing Sphinx configuration 1. Changing the HTML theme @@ -112,7 +112,7 @@ 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. @@ -120,21 +120,21 @@ highly recommended. - 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: Where to go from here +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, @@ -148,8 +148,8 @@ highly recommended. Read the Docs tutorial ---------------------- -0. What is Read the Docs -1. Getting started +1. What is Read the Docs +2. Getting started 1. Preparing our project on GitHub @@ -181,7 +181,7 @@ Read the Docs tutorial - Configure your email for build failure notification (until we turn them on by default) -2. Improving our workflow +3. Improving our workflow 1. Rendering our documentation from pull requests @@ -193,25 +193,25 @@ Read the Docs tutorial - Essentially the steps already described in our Custom Domains reference -3. Versioning documentation +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 -4. Customizing the build process +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 -5. Getting insights from your projects +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 -6. Managing translations -7. Where to go from here +7. Managing translations +8. Where to go from here - Reference our existing guides, prominent projects already using RTD, our support form, our contributing documentation From 7156c22dd7d713d62baeddfc474bd0bc196674e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 23:00:55 +0200 Subject: [PATCH 09/21] Remove outdated steps Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/development/design/new-sphinx-guides.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index ba04c5953c4..d0995dcbf50 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -75,11 +75,9 @@ highly recommended. 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!) + - See how the various formats change the output (yay!) 3. Appendix: Simplify documentation building by using Make [3]_ From e24fee6bd3c7998b1710aab6f1ff9cf70459e8ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 22:58:50 +0200 Subject: [PATCH 10/21] Autonumbering --- docs/development/design/new-sphinx-guides.rst | 70 +++++++++---------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index d0995dcbf50..d3d6d69b795 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -17,27 +17,27 @@ Sphinx tutorial Appendixes are optional, i.e. not required to follow the tutorial, but highly recommended. -1. The Sphinx way +#. 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 +#. 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 +#. Getting started - 1. Creating our project + #. 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 + #. Installing Sphinx and cookiecutter in a new development environment - Install Python (or miniforge) - Create a virtual environment (and/or conda environment) @@ -46,7 +46,7 @@ highly recommended. - Install Sphinx inside the virtual environment - Check that ``sphinx-build --help`` works (yay!) - 3. Creating the documentation layout + #. Creating the documentation layout - Apply our cookiecutter to create a minimal ``docs/`` directory (similar to what ``sphinx-quickstart`` does, but @@ -55,15 +55,15 @@ highly recommended. and a MyST index, if at all) [1]_ - Check that the correct files are created (yay!) - 4. Appendix: Using version control + #. 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 +#. First steps to document our project using Sphinx - 1. Converting our documentation to local HTML + #. Converting our documentation to local HTML - Create (or minimally tweak) ``index.md`` - Build the HTML output using @@ -73,44 +73,44 @@ highly recommended. - Open http://localhost:8000 in a web browser, and see the HTML documentation (yay!) - 2. Converting our documentation to other formats + #. 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!) - 3. Appendix: Simplify documentation building by using Make [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!) - 4. Appendix: PDF without LaTeX using rinoh (beta) + #. Appendix: PDF without LaTeX using rinoh (beta) -5. Customizing Sphinx configuration +#. Customizing Sphinx configuration - 1. Changing the HTML theme + #. 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 + #. 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 + #. 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 +#. Writing narrative documentation with Sphinx - First focus on ``index.md``, diving more into Markdown and mentioning Semantic Line Breaks. @@ -118,21 +118,21 @@ highly recommended. - Then continue introducing elements of the syntax to add pictures, cross-references, and the like. -7. Describing code in Sphinx +#. 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 +#. 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 -10. Appendix: Using Jupyter notebooks inside Sphinx -11. Appendix: Where to go from here +#. Appendix: Using Jupyter notebooks inside Sphinx +#. Appendix: Where to go from here - Refer the user to the Sphinx, reST and MyST references, prominent projects already using Sphinx, @@ -146,10 +146,10 @@ highly recommended. Read the Docs tutorial ---------------------- -1. What is Read the Docs -2. Getting started +#. What is Read the Docs +#. Getting started - 1. Preparing our project on GitHub + #. 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, @@ -160,7 +160,7 @@ Read the Docs tutorial helps mimicking the `sphinx-quickstart` or `cookiecutter` step without having to checkout the code locally) - 2. Importing our project to Read the Docs + #. Importing our project to Read the Docs - Sign up on RTD - Connect your GitHub account (is this step necessary @@ -171,7 +171,7 @@ Read the Docs tutorial - The project is created on RTD - Browse "builds", wait a couple of minutes, open the docs (yay!) - 3. Basic configuration changes + #. Basic configuration changes - Add a description, homepage, and tags - Browse other project with similar tags as yours @@ -179,37 +179,37 @@ Read the Docs tutorial - Configure your email for build failure notification (until we turn them on by default) -3. Improving our workflow +#. Improving our workflow - 1. Rendering our documentation from pull requests + #. 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 + #. Using custom domains - Essentially the steps already described in our Custom Domains reference -4. Versioning documentation +#. 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 +#. 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 +#. 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 +#. Managing translations +#. Where to go from here - Reference our existing guides, prominent projects already using RTD, our support form, our contributing documentation From c1a16e9d7c0c12e746ba8f6b4ecd398fa0c23f2d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 23:01:46 +0200 Subject: [PATCH 11/21] Style --- docs/development/design/new-sphinx-guides.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index d3d6d69b795..3eb92047c73 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -76,7 +76,7 @@ highly recommended. #. Converting our documentation to other formats - Build PseudoXML using ``make pseudoxml`` - - Build Text using ``make text`` + - Build Text using ``make text`` - See how the various formats change the output (yay!) #. Appendix: Simplify documentation building by using Make [3]_ From ffed9e2c592ca0ef6610d69001b139ba70436a01 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 23:02:48 +0200 Subject: [PATCH 12/21] Add appendix about docutils document tree --- docs/development/design/new-sphinx-guides.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index 3eb92047c73..b39045f76c7 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -132,6 +132,7 @@ highly recommended. - 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, From a13a15715bc08fd9c41100aa2e6f030494c50a8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 23:03:29 +0200 Subject: [PATCH 13/21] Rewording for fun and profit! --- docs/development/design/new-sphinx-guides.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index b39045f76c7..e17b4dedd3f 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -147,7 +147,7 @@ highly recommended. Read the Docs tutorial ---------------------- -#. What is Read the Docs +#. The Read the Docs way #. Getting started #. Preparing our project on GitHub From 4f61f0f2367cadba6d6d98f0472ef89dd4633b96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 23:04:35 +0200 Subject: [PATCH 14/21] Clarify use of the starting template --- docs/development/design/new-sphinx-guides.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index e17b4dedd3f..327cb073e1c 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -152,12 +152,9 @@ Read the Docs tutorial #. 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 + - Fork a starter GitHub repository (something like `our demo template `_, - as a starting point + as a starting point that helps mimicking the `sphinx-quickstart` or `cookiecutter` step without having to checkout the code locally) From 6ecf5175429999835d73e902eb598486738cfcb8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 23:05:59 +0200 Subject: [PATCH 15/21] Simplify signup process --- docs/development/design/new-sphinx-guides.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index 327cb073e1c..6d9266224d0 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -160,10 +160,7 @@ Read the Docs tutorial #. 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) + - 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 From 796aebbe0cc6012f26a12d7e859af9fe6bd48128 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 23:06:12 +0200 Subject: [PATCH 16/21] Emphasize viewing the build logs --- docs/development/design/new-sphinx-guides.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index 6d9266224d0..27e26db0323 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -164,7 +164,8 @@ Read the Docs tutorial - 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!) + - Browse "builds", open the build live logs, wait a couple of minutes, + open the docs (yay!) #. Basic configuration changes From 21800d05b168cb818ec5a5b196bead58a328e8c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 23:10:14 +0200 Subject: [PATCH 17/21] Remove mention of tag browsing --- docs/development/design/new-sphinx-guides.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index 27e26db0323..e40079dadd9 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -170,8 +170,6 @@ Read the Docs tutorial #. 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) From 16aa067604332fbd5561f7ce6828bec2ba628ca6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 23:13:49 +0200 Subject: [PATCH 18/21] Merge pull request configuration with previous section --- docs/development/design/new-sphinx-guides.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index e40079dadd9..675760806d4 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -172,11 +172,6 @@ Read the Docs tutorial - Add a description, homepage, and tags - Configure your email for build failure notification (until we turn them on by default) - -#. Improving our workflow - - #. 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!) From 38d78fc847ed57c1dd051a228b65a9daa0d7a3c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 23:14:32 +0200 Subject: [PATCH 19/21] Make only brief mention of domain configuration --- docs/development/design/new-sphinx-guides.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index 675760806d4..4bf67f74e23 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -176,10 +176,6 @@ Read the Docs tutorial - 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!) - #. Using custom domains - - - Essentially the steps already described in our Custom Domains reference - #. Versioning documentation - Explain how to manage versions on RTD: create release branches, @@ -198,10 +194,11 @@ Read the Docs tutorial - 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, - our support form, our contributing documentation + domain configuration, our support form, our contributing documentation Possible new how-to Guides -------------------------- From a981d3b5f9605c8ad33e49057734502f6973581d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 22 Apr 2021 23:14:58 +0200 Subject: [PATCH 20/21] Present RTD config earlier --- docs/development/design/new-sphinx-guides.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index 4bf67f74e23..add040d05e9 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -176,6 +176,11 @@ Read the Docs tutorial - 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, @@ -183,11 +188,6 @@ Read the Docs tutorial selectively build versions - Intermediate topics: hide versions, create Automation Rules -#. 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 - #. Getting insights from your projects - Move around the project, explore results in Traffic Analytics From d554f8fbb08cf48c0148233d0b5f21e95b7aaa65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Wed, 23 Jun 2021 07:25:36 +0200 Subject: [PATCH 21/21] Add note about ongoing work with the new Sphinx guides --- docs/development/design/new-sphinx-guides.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/development/design/new-sphinx-guides.rst b/docs/development/design/new-sphinx-guides.rst index add040d05e9..71ed2566116 100644 --- a/docs/development/design/new-sphinx-guides.rst +++ b/docs/development/design/new-sphinx-guides.rst @@ -1,6 +1,12 @@ 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.