From a2664e9e89a84b08771b1e24f9cae9ffb7f19108 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 8 Aug 2024 12:53:30 +0200 Subject: [PATCH 01/29] Fix indent --- docs/user/versions.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/user/versions.rst b/docs/user/versions.rst index 0aadefc4210..ba4a121befb 100644 --- a/docs/user/versions.rst +++ b/docs/user/versions.rst @@ -111,6 +111,7 @@ all of which can be reconfigured if necessary: - If you have documentation changes on a **long-lived branch**, you can build those too, to see how the new docs will be built. - This is most useful for **release branches**, which are maintained over time for a specific release. An example would be a ``2.1`` branch that is kept up to date with the latest ``2.1.x`` release. + This is most useful for **release branches**, which are maintained over time for a specific release. + An example would be a ``2.1`` branch that is kept up to date with the latest ``2.1.x`` release. .. _PEP 440: https://www.python.org/dev/peps/pep-0440/ From 65ee55f613d9f253eed5123fd72dd7c596c0f9e8 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 15 Aug 2024 14:46:57 +0200 Subject: [PATCH 02/29] Noodling on doctools --- docs/user/index.rst | 1 + docs/user/intro/doctools.rst | 16 +++++ docs/user/intro/jsdoc.rst | 22 ++++++ docs/user/intro/mkdocs.rst | 125 +++++++++++++++++++++++++++++++++++ docs/user/intro/sphinx.rst | 26 ++++++++ 5 files changed, 190 insertions(+) create mode 100644 docs/user/intro/doctools.rst create mode 100644 docs/user/intro/jsdoc.rst create mode 100644 docs/user/intro/mkdocs.rst create mode 100644 docs/user/intro/sphinx.rst diff --git a/docs/user/index.rst b/docs/user/index.rst index bcdce68e49d..c3b1c421a7b 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -7,6 +7,7 @@ Read the Docs: documentation simplified :caption: Getting started /tutorial/index + /intro/doctools /intro/getting-started-with-sphinx /intro/getting-started-with-mkdocs /intro/import-guide diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst new file mode 100644 index 00000000000..38ec3b9a209 --- /dev/null +++ b/docs/user/intro/doctools.rst @@ -0,0 +1,16 @@ +Supported doc tools +=================== + +Read the Docs provides hosting for documentation, +regardless of what tool you use to build it. + +Here are minimal configuration examples for some common tools, +with more coming soon. + +.. toctree:: + :maxdepth: 2 + :caption: Supported doctools + + Hosting Sphinx documentation on Read the Docs + Hosting Mkdocs documentation on Read the Docs + Hosting JSDoc documentation on Read the Docs diff --git a/docs/user/intro/jsdoc.rst b/docs/user/intro/jsdoc.rst new file mode 100644 index 00000000000..0325cc0e9d8 --- /dev/null +++ b/docs/user/intro/jsdoc.rst @@ -0,0 +1,22 @@ +JSDoc +----- + +JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc. +You add documentation comments directly to your source code, right alongside the code itself. +The JSDoc tool will scan your source code and generate HTML documentation. + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + build: + os: "ubuntu-22.04" + tools: + python: "3.9" + nodejs: "16" + jobs: + post_install: + # Install dependencies defined in your ``package.json`` + - npm ci + # Install any other extra dependencies to build the docs + - npm install -g jsdoc diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst new file mode 100644 index 00000000000..56324ecfb47 --- /dev/null +++ b/docs/user/intro/mkdocs.rst @@ -0,0 +1,125 @@ +Mkdocs on Read the Docs +======================= + +MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. + +.. TODO The code comments here are pre-addons right? cos there is no manipulation + + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + build: + os: ubuntu-22.04 + tools: + python: "3" + # Since Read the Docs manipulates that `mkdocs.yml` and it does not support `!ENV`, + # we use `build.commands` here because we need `!ENV` in our `mkdocs.yml`. + # + commands: + # Install Material for MkDocs Insiders + # https://squidfunk.github.io/mkdocs-material/insiders/getting-started/ + # + # Create GH_TOKEN environment variable on Read the Docs + # https://docs.readthedocs.io/en/stable/guides/private-python-packages.html + - pip install mkdocs-material + - mkdocs build --site-dir $READTHEDOCS_OUTPUT/html + +Configuring Mkdocs and Read the Docs addons +------------------------------------------- + +To get the best integration with Read the Docs, +you need to make the following configuration changes to your Mkdocs config: + +#. Set the site URL using a :doc:`Read the Docs environment variable `: + + .. code-block:: yaml + :caption: mkdocs.yml + + site_url: !ENV READTHEDOCS_CANONICAL_URL + +#. Configure search to use Read the Docs search instead of Mkdocs search: + + .. code-block:: js + :caption: javascript/readthedocs.js + + document.addEventListener("DOMContentLoaded", function(event) { + // Trigger Read the Docs' search addon instead of Material MkDocs default + document.querySelector(".md-search__input").addEventListener("focus", (e) => { + const event = new CustomEvent("readthedocs-search-show"); + document.dispatchEvent(event); + }); + }); + +#. Include ``javascript/readthedocs.js`` in the Mkdocs build: + + .. code-block:: yaml + :caption: mkdocs.yml + + extra_javascript: + - javascript/readthedocs.js + + +Integrating Read the Docs version menu into your site navigation +----------------------------------------------------------------- + +To integrate the version menu into your site navigation + +#. Override the ``main.html`` template to include the data in the ``meta`` attribute: + + .. code-block:: html + :caption: overrides/main.html + + + {% extends "base.html" %} + + {% block site_meta %} + {{ super() }} + + {% endblock %} + +#. Parse the version data into a dropdown menu using JS in ``javascript/readthedocs.js``: + + .. code-block:: js + :caption: javascript/readthedocs.js + + // Use CustomEvent to generate the version selector + document.addEventListener( + "readthedocs-addons-data-ready", + function (event) { + const config = event.detail.data(); + const versioning = ` +
+ + + +
`; + + document.querySelector(".md-header__topic").insertAdjacentHTML("beforeend", versioning); + }); + +#. Make sure that ``javascript/readthedocs.js`` is included in the Mkdocs build: + + .. code-block:: yaml + :caption: mkdocs.yml + + extra_javascript: + - javascript/readthedocs.js + +.. toctree:: + :maxdepth: 2 + :caption: Getting started + + /intro/getting-started-with-mkdocs + diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst new file mode 100644 index 00000000000..bfbcdc1cf2d --- /dev/null +++ b/docs/user/intro/sphinx.rst @@ -0,0 +1,26 @@ +Sphinx +====== + +Sphinx is a powerful documentation generator that +has many features for writing technical documentation. + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + sphinx: + configuration: docs/conf.py + +Configuring Sphinx and Read the Docs addons +------------------------------------------- + +To get the best integration with Read the Docs, +you need to make a few configuration changes to your + + +Example repository +------------------- + + +Sphinx tutorial +--------------- From 2a6841deb58b5d3891c96c8a3d1c55a5b9a2f1ec Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 15 Aug 2024 14:54:09 +0200 Subject: [PATCH 03/29] Pre-commit --- docs/user/intro/mkdocs.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index 56324ecfb47..d60162ef510 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -122,4 +122,3 @@ To integrate the version menu into your site navigation :caption: Getting started /intro/getting-started-with-mkdocs - From 37fa1bca6c9ca8fd6b1e70353a56c904c4d12ffd Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 15 Aug 2024 17:53:51 +0200 Subject: [PATCH 04/29] Remove mkdocs getting started guide --- docs/user/guides/canonical-urls.rst | 2 +- docs/user/index.rst | 1 - .../intro/getting-started-with-mkdocs.rst | 87 ------------------- docs/user/intro/mkdocs.rst | 26 +++++- docs/user/tutorials/index.rst | 4 +- 5 files changed, 25 insertions(+), 95 deletions(-) delete mode 100644 docs/user/intro/getting-started-with-mkdocs.rst diff --git a/docs/user/guides/canonical-urls.rst b/docs/user/guides/canonical-urls.rst index 91e466646ff..bdd71f461d0 100644 --- a/docs/user/guides/canonical-urls.rst +++ b/docs/user/guides/canonical-urls.rst @@ -26,7 +26,7 @@ and letting Read the Docs define it. MkDocs ~~~~~~ -For :doc:`MkDocs ` we do not define your canonical domain automatically, +For :doc:`MkDocs ` we do not define your canonical domain automatically, but you can use the site_url_ setting to set a similar value. In your ``mkdocs.yml``, define the following: diff --git a/docs/user/index.rst b/docs/user/index.rst index c3b1c421a7b..5c2d8a32cfa 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -9,7 +9,6 @@ Read the Docs: documentation simplified /tutorial/index /intro/doctools /intro/getting-started-with-sphinx - /intro/getting-started-with-mkdocs /intro/import-guide /examples diff --git a/docs/user/intro/getting-started-with-mkdocs.rst b/docs/user/intro/getting-started-with-mkdocs.rst deleted file mode 100644 index 150d07ccb30..00000000000 --- a/docs/user/intro/getting-started-with-mkdocs.rst +++ /dev/null @@ -1,87 +0,0 @@ -Getting started with MkDocs -=========================== - -.. meta:: - :description lang=en: Get started writing technical documentation with MkDocs and publishing to Read the Docs. - - -MkDocs is a documentation generator that focuses on speed and simplicity. -It has many great features including: - -* Preview your documentation as you write it -* Easy customization with themes and extensions -* Writing documentation with Markdown - -.. note:: - - MkDocs is a great choice for building technical documentation. - However, Read the Docs also supports :doc:`Sphinx `, - another tool for writing and building documentation. - - -Quick start ------------ - -.. seealso:: If you already have a Mkdocs project, check out our :doc:`/intro/import-guide` guide. - -Assuming you have Python already, `install MkDocs`_: - -.. prompt:: bash $ - - pip install mkdocs - -Setup your MkDocs project: - -.. prompt:: bash $ - - mkdocs new . - -This command creates ``mkdocs.yml`` which holds your MkDocs configuration, -and ``docs/index.md`` which is the Markdown file -that is the entry point for your documentation. - -You can edit this ``index.md`` file to add more details about your project -and then you can build your documentation: - -.. prompt:: bash $ - - mkdocs serve - -This command builds your Markdown files into HTML -and starts a development server to browse your documentation. -Open up http://127.0.0.1:8000/ in your web browser to see your documentation. -You can make changes to your Markdown files and your docs will automatically rebuild. - -.. figure:: /_static/images/first-steps/mkdocs-hello-world.png - :figwidth: 500px - :align: center - - Your MkDocs project is built - -Once you have your documentation in a public repository such as GitHub, Bitbucket, or GitLab, -you can start using Read the Docs by :doc:`importing your docs `. - -.. _install MkDocs: https://www.mkdocs.org/user-guide/installation/ - -.. warning:: - - We strongly recommend to :doc:`pin the MkDocs version ` - used for your project to build the docs to avoid potential future incompatibilities. - -Get inspired! -------------- - -You might learn more and find the first ingredients for starting your own documentation project by looking at :doc:`/examples` - view live example renditions and copy & paste from the accompanying source code. - -External resources ------------------- - -Here are some external resources to help you learn more about MkDocs. - -* `MkDocs documentation`_ -* `Markdown syntax guide`_ -* `Writing your docs with MkDocs`_ - -.. _MkDocs documentation: https://www.mkdocs.org/ -.. _Markdown syntax guide: https://daringfireball.net/projects/markdown/syntax -.. _Writing your docs with MkDocs: https://www.mkdocs.org/user-guide/writing-your-docs/ diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index d60162ef510..20b6fd8fc34 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -1,6 +1,9 @@ Mkdocs on Read the Docs ======================= +.. meta:: + :description lang=en: Hosting MkDocs on Read the Docs. + MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. .. TODO The code comments here are pre-addons right? cos there is no manipulation @@ -26,6 +29,15 @@ MkDocs is a fast, simple and downright gorgeous static site generator that's gea - pip install mkdocs-material - mkdocs build --site-dir $READTHEDOCS_OUTPUT/html +Quick start +----------- + +- If you have an existing Mkdocs project your want to host on Read the Docs, check out our :doc:`/intro/import-guide` guide. + +- If you're new to Mkdocs, check out the official `Getting started with MkDocs`_ guide. + +.. _Getting started with MkDocs: https://www.mkdocs.org/getting-started/ + Configuring Mkdocs and Read the Docs addons ------------------------------------------- @@ -117,8 +129,14 @@ To integrate the version menu into your site navigation extra_javascript: - javascript/readthedocs.js -.. toctree:: - :maxdepth: 2 - :caption: Getting started - /intro/getting-started-with-mkdocs +Further reading +--------------- + +* `MkDocs documentation`_ +* `Markdown syntax guide`_ +* `Writing your docs with MkDocs`_ + +.. _MkDocs documentation: https://www.mkdocs.org/ +.. _Markdown syntax guide: https://daringfireball.net/projects/markdown/syntax +.. _Writing your docs with MkDocs: https://www.mkdocs.org/user-guide/writing-your-docs/ diff --git a/docs/user/tutorials/index.rst b/docs/user/tutorials/index.rst index bc04a479b3c..8496d8b6065 100644 --- a/docs/user/tutorials/index.rst +++ b/docs/user/tutorials/index.rst @@ -14,7 +14,7 @@ Tutorials It supports both reStructuredText and Markdown formats, and can generate rich API documentation from your source code. We recommend Sphinx for documentation that includes API reference documentation. -⏩️ :doc:`/intro/getting-started-with-mkdocs` +⏩️ :doc:`/intro/mkdocs` Another great and popular tool is MkDocs. This is especially popular because of its default of using Markdown. This tool is well-supported on our platform and that's why we have a tutorial. @@ -38,7 +38,7 @@ Tutorials /tutorial/index /intro/getting-started-with-sphinx - /intro/getting-started-with-mkdocs + /intro/mkdocs /intro/import-guide /config-file/index /examples From 5b80ab061b888857f5e88fcf3813576fe286e780 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Wed, 28 Aug 2024 14:18:20 +0200 Subject: [PATCH 05/29] Typo --- docs/user/intro/mkdocs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index 20b6fd8fc34..df74fcc3e5d 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -32,7 +32,7 @@ MkDocs is a fast, simple and downright gorgeous static site generator that's gea Quick start ----------- -- If you have an existing Mkdocs project your want to host on Read the Docs, check out our :doc:`/intro/import-guide` guide. +- If you have an existing Mkdocs project you want to host on Read the Docs, check out our :doc:`/intro/import-guide` guide. - If you're new to Mkdocs, check out the official `Getting started with MkDocs`_ guide. From 6951e8015e3de706f30a3ff513d778fb33429871 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Wed, 28 Aug 2024 14:18:54 +0200 Subject: [PATCH 06/29] Skip jsdoc for now --- docs/user/intro/doctools.rst | 3 +-- docs/user/intro/jsdoc.rst | 22 ---------------------- 2 files changed, 1 insertion(+), 24 deletions(-) delete mode 100644 docs/user/intro/jsdoc.rst diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 38ec3b9a209..111afae1f6f 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -12,5 +12,4 @@ with more coming soon. :caption: Supported doctools Hosting Sphinx documentation on Read the Docs - Hosting Mkdocs documentation on Read the Docs - Hosting JSDoc documentation on Read the Docs + Hosting MaterialMkdocs documentation on Read the Docs diff --git a/docs/user/intro/jsdoc.rst b/docs/user/intro/jsdoc.rst deleted file mode 100644 index 0325cc0e9d8..00000000000 --- a/docs/user/intro/jsdoc.rst +++ /dev/null @@ -1,22 +0,0 @@ -JSDoc ------ - -JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc. -You add documentation comments directly to your source code, right alongside the code itself. -The JSDoc tool will scan your source code and generate HTML documentation. - -.. code-block:: yaml - :caption: .readthedocs.yaml - - version: 2 - build: - os: "ubuntu-22.04" - tools: - python: "3.9" - nodejs: "16" - jobs: - post_install: - # Install dependencies defined in your ``package.json`` - - npm ci - # Install any other extra dependencies to build the docs - - npm install -g jsdoc From 58d88135fd4fa3e461fd812156ccd9fc7c867b26 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Wed, 28 Aug 2024 14:30:29 +0200 Subject: [PATCH 07/29] Add clarity on mkdocs vs material --- docs/user/intro/doctools.rst | 2 +- docs/user/intro/mkdocs.rst | 35 ++++++++++++++++++++--------------- 2 files changed, 21 insertions(+), 16 deletions(-) diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 111afae1f6f..f4471793c25 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -12,4 +12,4 @@ with more coming soon. :caption: Supported doctools Hosting Sphinx documentation on Read the Docs - Hosting MaterialMkdocs documentation on Read the Docs + Hosting Material for Mkdocs documentation on Read the Docs diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index df74fcc3e5d..13365e855d4 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -1,12 +1,17 @@ -Mkdocs on Read the Docs -======================= +Material for MkDocs on Read the Docs +==================================== .. meta:: - :description lang=en: Hosting MkDocs on Read the Docs. + :description lang=en: Hosting Material for MkDocs on Read the Docs. -MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. +MkDocs is a fast, simple static site generator that's geared towards building project documentation. +Material for MkDocs is a powerful documentation framework on top of MkDocs. -.. TODO The code comments here are pre-addons right? cos there is no manipulation +.. note:: + + This page is explicitly about Material for MkDocs. We're working on a guide for plain MkDocs as well. + +.. TODO The code comments for this next coe block are pre-addons right? cos there is no manipulation .. code-block:: yaml @@ -32,17 +37,17 @@ MkDocs is a fast, simple and downright gorgeous static site generator that's gea Quick start ----------- -- If you have an existing Mkdocs project you want to host on Read the Docs, check out our :doc:`/intro/import-guide` guide. +- If you have an existing Material for MkDocs project you want to host on Read the Docs, check out our :doc:`/intro/import-guide` guide. -- If you're new to Mkdocs, check out the official `Getting started with MkDocs`_ guide. +- If you're new to Material for MkDocs, check out the official `Getting started with Material for MkDocs`_ guide. -.. _Getting started with MkDocs: https://www.mkdocs.org/getting-started/ +.. _Getting started with Material for MkDocs: https://squidfunk.github.io/mkdocs-material/getting-started/ -Configuring Mkdocs and Read the Docs addons +Configuring MkDocs and Read the Docs addons ------------------------------------------- To get the best integration with Read the Docs, -you need to make the following configuration changes to your Mkdocs config: +you need to make the following configuration changes to your Material for MkDocs config: #. Set the site URL using a :doc:`Read the Docs environment variable `: @@ -51,7 +56,7 @@ you need to make the following configuration changes to your Mkdocs config: site_url: !ENV READTHEDOCS_CANONICAL_URL -#. Configure search to use Read the Docs search instead of Mkdocs search: +#. Configure search to use Read the Docs search instead of the default search: .. code-block:: js :caption: javascript/readthedocs.js @@ -64,7 +69,7 @@ you need to make the following configuration changes to your Mkdocs config: }); }); -#. Include ``javascript/readthedocs.js`` in the Mkdocs build: +#. Include ``javascript/readthedocs.js`` in the MkDocs build: .. code-block:: yaml :caption: mkdocs.yml @@ -121,7 +126,7 @@ To integrate the version menu into your site navigation document.querySelector(".md-header__topic").insertAdjacentHTML("beforeend", versioning); }); -#. Make sure that ``javascript/readthedocs.js`` is included in the Mkdocs build: +#. Make sure that ``javascript/readthedocs.js`` is included in the MkDocs build: .. code-block:: yaml :caption: mkdocs.yml @@ -133,10 +138,10 @@ To integrate the version menu into your site navigation Further reading --------------- -* `MkDocs documentation`_ +* `Material for MkDocs documentation`_ * `Markdown syntax guide`_ * `Writing your docs with MkDocs`_ -.. _MkDocs documentation: https://www.mkdocs.org/ +.. _MkDocs documentation: https://squidfunk.github.io/mkdocs-material/setup/ .. _Markdown syntax guide: https://daringfireball.net/projects/markdown/syntax .. _Writing your docs with MkDocs: https://www.mkdocs.org/user-guide/writing-your-docs/ From 1b2d18bba05e3abcc079bc92a40cfacbb9751ea3 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Wed, 28 Aug 2024 14:39:16 +0200 Subject: [PATCH 08/29] link fix --- docs/user/intro/mkdocs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index 13365e855d4..b8b93304ab9 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -142,6 +142,6 @@ Further reading * `Markdown syntax guide`_ * `Writing your docs with MkDocs`_ -.. _MkDocs documentation: https://squidfunk.github.io/mkdocs-material/setup/ +.. _Material for MkDocs documentation: https://squidfunk.github.io/mkdocs-material/setup/ .. _Markdown syntax guide: https://daringfireball.net/projects/markdown/syntax .. _Writing your docs with MkDocs: https://www.mkdocs.org/user-guide/writing-your-docs/ From 1ce3d134cb07d7834354e07ea87f65ffeb28a472 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Wed, 28 Aug 2024 15:09:18 +0200 Subject: [PATCH 09/29] WIP --- docs/user/index.rst | 2 ++ docs/user/intro/mkdocs.rst | 16 ++++++++++++---- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/user/index.rst b/docs/user/index.rst index 5c2d8a32cfa..79a6834b24e 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -8,6 +8,8 @@ Read the Docs: documentation simplified /tutorial/index /intro/doctools + /intro/mkdocs + /intro/sphinx /intro/getting-started-with-sphinx /intro/import-guide /examples diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index b8b93304ab9..62c802d264c 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -43,8 +43,8 @@ Quick start .. _Getting started with Material for MkDocs: https://squidfunk.github.io/mkdocs-material/getting-started/ -Configuring MkDocs and Read the Docs addons -------------------------------------------- +Configuring Material for MkDocs and Read the Docs addons +-------------------------------------------------------- To get the best integration with Read the Docs, you need to make the following configuration changes to your Material for MkDocs config: @@ -78,8 +78,8 @@ you need to make the following configuration changes to your Material for MkDocs - javascript/readthedocs.js -Integrating Read the Docs version menu into your site navigation ------------------------------------------------------------------ +Integrating the Read the Docs version menu into your site navigation +-------------------------------------------------------------------- To integrate the version menu into your site navigation @@ -134,6 +134,14 @@ To integrate the version menu into your site navigation extra_javascript: - javascript/readthedocs.js +Example repo and demo +--------------------- + +Example repo:: + https://github.com/readthedocs/test-builds/tree/mkdocs-material + +Demo:: + https://test-builds.readthedocs.io/en/mkdocs-material/ Further reading --------------- From cc2d731ba0fbc5a95b4298b1edc871a3f2c296a7 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Mon, 2 Sep 2024 10:48:18 +0200 Subject: [PATCH 10/29] Review feedback --- docs/user/intro/doctools.rst | 4 ++-- docs/user/intro/mkdocs.rst | 45 +++++++++++++++++++++++++----------- 2 files changed, 34 insertions(+), 15 deletions(-) diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index f4471793c25..c6c14624e29 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -1,8 +1,8 @@ Supported doc tools =================== -Read the Docs provides hosting for documentation, -regardless of what tool you use to build it. +Read the Docs provides hosting for static html documentation generated by Sphinx, +MkDocs, Docusaurus and a variety of other tools. Here are minimal configuration examples for some common tools, with more coming soon. diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index 62c802d264c..b701264c6eb 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -46,17 +46,36 @@ Quick start Configuring Material for MkDocs and Read the Docs addons -------------------------------------------------------- -To get the best integration with Read the Docs, -you need to make the following configuration changes to your Material for MkDocs config: +For optimal integration with Read the Docs, make the optional following configuration changes to your Material for MkDocs config. -#. Set the site URL using a :doc:`Read the Docs environment variable `: +.. contents:: + :depth: 1 + :local: + :backlinks: none - .. code-block:: yaml - :caption: mkdocs.yml +Set the canonical URL +~~~~~~~~~~~~~~~~~~~~~ + +A :doc:`canonical URL ` allows you to specify the preferred version of a web page +to prevent duplicated content. + +Set your MkDocs `site URL`_ to your Read the Docs canonical URL using a +:doc:`Read the Docs environment variable `: + +.. code-block:: yaml + :caption: mkdocs.yml + + site_url: !ENV READTHEDOCS_CANONICAL_URL + +.. _Site URL: https://www.mkdocs.org/user-guide/configuration/#site_url + + +Configure Read the Docs search +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - site_url: !ENV READTHEDOCS_CANONICAL_URL +To configure your site to use :doc:`Read the Docs search ` instead of the default search: -#. Configure search to use Read the Docs search instead of the default search: +#. Add the following block of JavaScript: .. code-block:: js :caption: javascript/readthedocs.js @@ -69,7 +88,7 @@ you need to make the following configuration changes to your Material for MkDocs }); }); -#. Include ``javascript/readthedocs.js`` in the MkDocs build: +#. Include ``javascript/readthedocs.js`` in your MkDocs configuration: .. code-block:: yaml :caption: mkdocs.yml @@ -78,8 +97,8 @@ you need to make the following configuration changes to your Material for MkDocs - javascript/readthedocs.js -Integrating the Read the Docs version menu into your site navigation --------------------------------------------------------------------- +Integrate the Read the Docs version menu into your site navigation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To integrate the version menu into your site navigation @@ -126,7 +145,7 @@ To integrate the version menu into your site navigation document.querySelector(".md-header__topic").insertAdjacentHTML("beforeend", versioning); }); -#. Make sure that ``javascript/readthedocs.js`` is included in the MkDocs build: +#. Make sure that ``javascript/readthedocs.js`` is included in your MkDocs configuration: .. code-block:: yaml :caption: mkdocs.yml @@ -134,8 +153,8 @@ To integrate the version menu into your site navigation extra_javascript: - javascript/readthedocs.js -Example repo and demo ---------------------- +Example repository and demo +--------------------------- Example repo:: https://github.com/readthedocs/test-builds/tree/mkdocs-material From f81c7f7c83904b575fb5c83e08b95fb07cf1af5d Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Mon, 2 Sep 2024 11:32:59 +0200 Subject: [PATCH 11/29] Remove Getting Started with Sphinx --- docs/user/index.rst | 1 - .../intro/getting-started-with-sphinx.rst | 119 ------------------ 2 files changed, 120 deletions(-) delete mode 100644 docs/user/intro/getting-started-with-sphinx.rst diff --git a/docs/user/index.rst b/docs/user/index.rst index 79a6834b24e..5762f8510eb 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -10,7 +10,6 @@ Read the Docs: documentation simplified /intro/doctools /intro/mkdocs /intro/sphinx - /intro/getting-started-with-sphinx /intro/import-guide /examples diff --git a/docs/user/intro/getting-started-with-sphinx.rst b/docs/user/intro/getting-started-with-sphinx.rst deleted file mode 100644 index 48fb3b5c68d..00000000000 --- a/docs/user/intro/getting-started-with-sphinx.rst +++ /dev/null @@ -1,119 +0,0 @@ -Getting started with Sphinx -=========================== - -.. meta:: - :description lang=en: Get started writing technical documentation with Sphinx and publishing to Read the Docs. - -Sphinx is a powerful documentation generator that -has many great features for writing technical documentation including: - -* Generate web pages, printable PDFs, documents for e-readers (ePub), - and more all from the same sources -* You can use reStructuredText or :ref:`Markdown ` - to write documentation -* An extensive system of cross-referencing code and documentation -* Syntax highlighted code samples -* A vibrant ecosystem of first and third-party :doc:`extensions ` - -If you want to learn more about how to create your first Sphinx project, read on. -If you are interested in exploring the Read the Docs platform using an already existing Sphinx project, -check out :doc:`/tutorial/index`. - -Quick start ------------ - -.. seealso:: If you already have a Sphinx project, check out our :doc:`/intro/import-guide` guide. - -Assuming you have Python already, :doc:`install Sphinx `: - -.. prompt:: bash $ - - pip install sphinx - -Create a directory inside your project to hold your docs: - -.. prompt:: bash $ - - cd /path/to/project - mkdir docs - -Run ``sphinx-quickstart`` in there: - -.. prompt:: bash $ - - cd docs - sphinx-quickstart - -This quick start will walk you through creating the basic configuration; in most cases, you -can just accept the defaults. When it's done, you'll have an ``index.rst``, a -``conf.py`` and some other files. Add these to revision control. - -Now, edit your ``index.rst`` and add some information about your project. -Include as much detail as you like (refer to the :doc:`reStructuredText syntax ` -or `this template`_ if you need help). Build them to see how they look: - -.. prompt:: bash $ - - make html - -Your ``index.rst`` has been built into ``index.html`` -in your documentation output directory (typically ``_build/html/index.html``). -Open this file in your web browser to see your docs. - -.. figure:: /_static/images/first-steps/sphinx-hello-world.png - :figwidth: 500px - :align: center - - Your Sphinx project is built - -Edit your files and rebuild until you like what you see, then commit your changes and push to your public repository. -Once you have Sphinx documentation in a public repository, you can start using Read the Docs -by :doc:`importing your docs `. - -.. warning:: - - We strongly recommend to :doc:`pin the Sphinx version ` - used for your project to build the docs to avoid potential future incompatibilities. - -.. _this template: https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#id1 - -Using Markdown with Sphinx --------------------------- - -You can use `Markdown using MyST`_ and reStructuredText in the same Sphinx project. -We support this natively on Read the Docs, and you can do it locally: - -.. prompt:: bash $ - - pip install myst-parser - -Then in your ``conf.py``: - -.. code-block:: python - - extensions = ["myst_parser"] - -You can now continue writing your docs in ``.md`` files and it will work with Sphinx. -Read the `Getting started with MyST in Sphinx`_ docs for additional instructions. - -.. _Getting started with MyST in Sphinx: https://myst-parser.readthedocs.io/en/latest/sphinx/intro.html -.. _Markdown using MyST: https://myst-parser.readthedocs.io/en/latest/using/intro.html - - -Get inspired! -------------- - -You might learn more and find the first ingredients for starting your own documentation project by looking at :doc:`/examples` - view live example renditions and copy & paste from the accompanying source code. - - -External resources ------------------- - -Here are some external resources to help you learn more about Sphinx. - -* `Sphinx documentation`_ -* :doc:`RestructuredText primer ` -* `An introduction to Sphinx and Read the Docs for technical writers`_ - -.. _Sphinx documentation: https://www.sphinx-doc.org/ -.. _An introduction to Sphinx and Read the Docs for technical writers: https://www.ericholscher.com/blog/2016/jul/1/sphinx-and-rtd-for-writers/ From d0ed33649bb3c267a6c4cab209b5d5df6c3615e5 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Mon, 2 Sep 2024 11:39:35 +0200 Subject: [PATCH 12/29] Remove links as well --- docs/user/tutorials/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/tutorials/index.rst b/docs/user/tutorials/index.rst index 8496d8b6065..b457fb0bf80 100644 --- a/docs/user/tutorials/index.rst +++ b/docs/user/tutorials/index.rst @@ -9,7 +9,7 @@ Tutorials ⏩️ :doc:`/tutorial/index` This is where you should go if you are trying Read the Docs for the first time! -⏩️ :doc:`/intro/getting-started-with-sphinx` +⏩️ :doc:`/intro/sphinx` Sphinx is the most popular documentation tool on our platform. It supports both reStructuredText and Markdown formats, and can generate rich API documentation from your source code. We recommend Sphinx for documentation that includes API reference documentation. @@ -37,7 +37,7 @@ Tutorials :hidden: /tutorial/index - /intro/getting-started-with-sphinx + /intro/sphinx /intro/mkdocs /intro/import-guide /config-file/index From 512ab07a6005fcb0aa0771e36a4d364eb1e844b6 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Tue, 3 Sep 2024 11:03:31 +0200 Subject: [PATCH 13/29] Some updates to Sphinx and MkDocs pages --- docs/user/intro/mkdocs.rst | 36 ++++++------- docs/user/intro/sphinx.rst | 103 +++++++++++++++++++++++++++++++++---- 2 files changed, 109 insertions(+), 30 deletions(-) diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index b701264c6eb..3eadc34945c 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -2,7 +2,7 @@ Material for MkDocs on Read the Docs ==================================== .. meta:: - :description lang=en: Hosting Material for MkDocs on Read the Docs. + :description lang=en: Hosting Material for MkDocs sites on Read the Docs. MkDocs is a fast, simple static site generator that's geared towards building project documentation. Material for MkDocs is a powerful documentation framework on top of MkDocs. @@ -11,28 +11,26 @@ Material for MkDocs is a powerful documentation framework on top of MkDocs. This page is explicitly about Material for MkDocs. We're working on a guide for plain MkDocs as well. -.. TODO The code comments for this next coe block are pre-addons right? cos there is no manipulation - +Minimal configuration required to build an existing Material for MkDocs project on Read the Docs looks like this, +specifying a python toolchain on Ubuntu, defining the location of the installation requirements, and using the built-in +:ref:`mkdocs ` command: .. code-block:: yaml :caption: .readthedocs.yaml - version: 2 - build: - os: ubuntu-22.04 - tools: - python: "3" - # Since Read the Docs manipulates that `mkdocs.yml` and it does not support `!ENV`, - # we use `build.commands` here because we need `!ENV` in our `mkdocs.yml`. - # - commands: - # Install Material for MkDocs Insiders - # https://squidfunk.github.io/mkdocs-material/insiders/getting-started/ - # - # Create GH_TOKEN environment variable on Read the Docs - # https://docs.readthedocs.io/en/stable/guides/private-python-packages.html - - pip install mkdocs-material - - mkdocs build --site-dir $READTHEDOCS_OUTPUT/html + version: 2 + + build: + os: ubuntu-24.04 + tools: + python: "3" + + python: + install: + - requirements: requirements.txt + + mkdocs: + configuration: mkdocs.yml Quick start ----------- diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst index bfbcdc1cf2d..95c37ac42cd 100644 --- a/docs/user/intro/sphinx.rst +++ b/docs/user/intro/sphinx.rst @@ -1,26 +1,107 @@ -Sphinx -====== +Sphinx on Read the Docs +======================= + +.. meta:: + :description lang=en: Hosting Sphinx documentation on Read the Docs. Sphinx is a powerful documentation generator that has many features for writing technical documentation. +Minimal configuration required to build an existing Sphinx project on Read the Docs looks like this, +specifying a python 3.x toolchain on Ubuntu, defining the location of the installation requirements, and using the built-in +:ref:`mkdocs ` command: + + +.. TODO:: why do we install tree using apt_package here? Because it might not be in the requirements.txt but is still necessary? + .. code-block:: yaml :caption: .readthedocs.yaml - version: 2 - sphinx: - configuration: docs/conf.py + version: 2 + + build: + os: ubuntu-22.04 + tools: + python: "3" + apt_packages: + - tree + + sphinx: + configuration: docs/conf.py + + python: + install: + - requirements: requirements.txt + +Quick start +----------- + +- If you have an existing Sphinx project you want to host on Read the Docs, check out our :doc:`/intro/import-guide` guide. + +- If you're new to Sphinx, check out the official `Getting started with Sphinx`_ guide. + +- For a step by step tutorial on Read the Docs using an example Sphinx project, take a look at the :doc:`/tutorial/index`. + +.. _Getting started with Sphinx: https://www.sphinx-doc.org/en/master/usage/quickstart.html + Configuring Sphinx and Read the Docs addons -------------------------------------------- +-------------------------------------------------------- + +For optimal integration with Read the Docs, make the optional following configuration changes to your Spinx config. + +.. contents:: + :depth: 1 + :local: + :backlinks: none -To get the best integration with Read the Docs, -you need to make a few configuration changes to your +Set the canonical URL +~~~~~~~~~~~~~~~~~~~~~ +Configure Read the Docs search +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Example repository -------------------- +Integrate the Read the Docs version menu into your site navigation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Using Markdown with Sphinx +-------------------------- -Sphinx tutorial +You can use `Markdown using MyST`_ and reStructuredText in the same Sphinx project. +We support this natively on Read the Docs, and you can do it locally: + +.. prompt:: bash $ + + pip install myst-parser + +Then in your ``conf.py``: + +.. code-block:: python + + extensions = ["myst_parser"] + +You can now continue writing your docs in ``.md`` files and it will work with Sphinx. +Read the `Getting started with MyST in Sphinx`_ docs for additional instructions. + +.. _Getting started with MyST in Sphinx: https://myst-parser.readthedocs.io/en/latest/sphinx/intro.html +.. _Markdown using MyST: https://myst-parser.readthedocs.io/en/latest/using/intro.html + +Example repository and demo +--------------------------- + +Example repo:: + https://github.com/readthedocs/test-builds/tree/sphinx-7.0.x + +Demo:: + https://test-builds.readthedocs.io/en/sphinx-7.0.x + +Further reading --------------- + +* `Sphinx documentation`_ +* :doc:`RestructuredText primer ` +* `An introduction to Sphinx and Read the Docs for technical writers`_ + +.. _Sphinx documentation: https://www.sphinx-doc.org/ +.. _An introduction to Sphinx and Read the Docs for technical writers: https://www.ericholscher.com/blog/2016/jul/1/sphinx-and-rtd-for-writers/ + From 6de7081ab60b3fb7064eae63e578092529be21ea Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Tue, 3 Sep 2024 12:22:23 +0200 Subject: [PATCH 14/29] Directive not installed --- docs/user/intro/sphinx.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst index 95c37ac42cd..b206f95f1d0 100644 --- a/docs/user/intro/sphinx.rst +++ b/docs/user/intro/sphinx.rst @@ -12,7 +12,7 @@ specifying a python 3.x toolchain on Ubuntu, defining the location of the instal :ref:`mkdocs ` command: -.. TODO:: why do we install tree using apt_package here? Because it might not be in the requirements.txt but is still necessary? +.. TODO why do we install tree using apt_package here? Because it might not be in the requirements.txt but is still necessary? .. code-block:: yaml :caption: .readthedocs.yaml From 67e527be839b46820380dea00e0e8dc4169f921f Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 5 Sep 2024 09:53:11 +0200 Subject: [PATCH 15/29] WIP --- docs/user/intro/doctools.rst | 8 ++++---- docs/user/intro/mkdocs.rst | 4 ++-- docs/user/intro/sphinx.rst | 10 +++------- 3 files changed, 9 insertions(+), 13 deletions(-) diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index c6c14624e29..8f8dcc37489 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -1,5 +1,5 @@ -Supported doc tools -=================== +Supported tools +=============== Read the Docs provides hosting for static html documentation generated by Sphinx, MkDocs, Docusaurus and a variety of other tools. @@ -11,5 +11,5 @@ with more coming soon. :maxdepth: 2 :caption: Supported doctools - Hosting Sphinx documentation on Read the Docs - Hosting Material for Mkdocs documentation on Read the Docs + Sphinx + Material for Mkdocs diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index 3eadc34945c..738e1fea0c5 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -1,5 +1,5 @@ -Material for MkDocs on Read the Docs -==================================== +Material for MkDocs +=================== .. meta:: :description lang=en: Hosting Material for MkDocs sites on Read the Docs. diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst index b206f95f1d0..72ad7646fb6 100644 --- a/docs/user/intro/sphinx.rst +++ b/docs/user/intro/sphinx.rst @@ -8,23 +8,19 @@ Sphinx is a powerful documentation generator that has many features for writing technical documentation. Minimal configuration required to build an existing Sphinx project on Read the Docs looks like this, -specifying a python 3.x toolchain on Ubuntu, defining the location of the installation requirements, and using the built-in -:ref:`mkdocs ` command: +specifying a python 3.x toolchain on Ubuntu, using the built-in :ref:`mkdocs ` command, +and defining the location of the installation requirements: -.. TODO why do we install tree using apt_package here? Because it might not be in the requirements.txt but is still necessary? - .. code-block:: yaml :caption: .readthedocs.yaml version: 2 build: - os: ubuntu-22.04 + os: ubuntu-24.04 tools: python: "3" - apt_packages: - - tree sphinx: configuration: docs/conf.py From 7a1527e0fca379e7cb91d953498097270da91b7b Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 5 Sep 2024 10:15:38 +0200 Subject: [PATCH 16/29] Shorter! --- docs/user/intro/sphinx.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst index 72ad7646fb6..76f1a4ef7cf 100644 --- a/docs/user/intro/sphinx.rst +++ b/docs/user/intro/sphinx.rst @@ -1,5 +1,5 @@ -Sphinx on Read the Docs -======================= +Sphinx +====== .. meta:: :description lang=en: Hosting Sphinx documentation on Read the Docs. From 4b5251268876b961b7e5eb4890cd7940b4533479 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 5 Sep 2024 11:20:21 +0200 Subject: [PATCH 17/29] Add canonical url for sphinx --- docs/user/intro/sphinx.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst index 76f1a4ef7cf..2174a2c0d53 100644 --- a/docs/user/intro/sphinx.rst +++ b/docs/user/intro/sphinx.rst @@ -54,6 +54,20 @@ For optimal integration with Read the Docs, make the optional following configur Set the canonical URL ~~~~~~~~~~~~~~~~~~~~~ +A :doc:`canonical URL ` allows you to specify the preferred version of a web page +to prevent duplicated content. + +Set your `html_baseurl`_ to your Read the Docs canonical URL using a +:doc:`Read the Docs environment variable `: + +.. code-block:: py + :caption: conf.py + + html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") + + +.. _html_baseurl: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl + Configure Read the Docs search ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From dc63be4639902ea4ba10cd177b15fe79c5f639af Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 5 Sep 2024 13:57:26 +0200 Subject: [PATCH 18/29] Add see also --- docs/user/intro/sphinx.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst index 2174a2c0d53..54e9705a114 100644 --- a/docs/user/intro/sphinx.rst +++ b/docs/user/intro/sphinx.rst @@ -78,7 +78,7 @@ Using Markdown with Sphinx -------------------------- You can use `Markdown using MyST`_ and reStructuredText in the same Sphinx project. -We support this natively on Read the Docs, and you can do it locally: +We support this natively on Read the Docs, and you can also use locally by installing ``myst-parser``: .. prompt:: bash $ @@ -91,11 +91,20 @@ Then in your ``conf.py``: extensions = ["myst_parser"] You can now continue writing your docs in ``.md`` files and it will work with Sphinx. -Read the `Getting started with MyST in Sphinx`_ docs for additional instructions. -.. _Getting started with MyST in Sphinx: https://myst-parser.readthedocs.io/en/latest/sphinx/intro.html +.. seealso:: + + `Getting started with MyST in Sphinx `_ + + :doc:`/guides/migrate-rest-myst` + Learn how to use references between different Sphinx projects, for instance between subprojects + + :doc:`/guides/migrate-rest-myst` + Start writing Markdown in your existing reStructuredText project, or migrate it completely. + .. _Markdown using MyST: https://myst-parser.readthedocs.io/en/latest/using/intro.html + Example repository and demo --------------------------- From 7f8dfac0b0cff6cd75ac1f9ee163ef863278d90f Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 5 Sep 2024 15:19:57 +0200 Subject: [PATCH 19/29] Complete instructions --- docs/user/intro/mkdocs.rst | 22 ++++++++++++++++++++- docs/user/intro/sphinx.rst | 40 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 1 deletion(-) diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index 738e1fea0c5..a6884eac9a4 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -98,7 +98,7 @@ To configure your site to use :doc:`Read the Docs search `__, +:doc:`Server side search ` already works out of the box. + +If you're using a different theme, enable :doc:`Server side search `: + +#. Add a snippet of JavaScript: + + .. code-block:: js + :caption: readthedocs.js + + + // Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav. + document.querySelector("[role='search'] input").addEventListener("focusin", () => { + const event = new CustomEvent("readthedocs-search-show"); + document.dispatchEvent(event); + }); + +#. Include it in your build: + + .. code-block:: py + :caption: conf.py + + html_js_files = [ + readthedocs.js, + ] + + Integrate the Read the Docs version menu into your site navigation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you're using the `Read the Docs Sphinx Theme `__, the :ref:`flyout-menu:Addons flyout menu` is already fully integrated. + +You *may* need to set `flyout_display` to `hidden `_ in your ``conf.py`` so as not to display two identical menus: + +.. code-block:: py + :caption: conf.py + + html_theme_options = { + 'flyout_display': 'hidden', + } + +If you're using a different theme, the flyout menu will display in the default bottom right side of your docs. + Using Markdown with Sphinx -------------------------- From c7216e936a3a99481e0326da48a344937f73c26c Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 5 Sep 2024 15:29:56 +0200 Subject: [PATCH 20/29] Add test card display --- docs/conf.py | 1 + docs/user/intro/doctools.rst | 48 ++++++++++++++++++++++++++++++++---- requirements/docs.in | 1 + 3 files changed, 45 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ddd04d7336d..be00115c2c1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -24,6 +24,7 @@ "notfound.extension", "sphinx_copybutton", "sphinx_design", + "sphinx_design_elements", "sphinx_tabs.tabs", "sphinx-prompt", "sphinx.ext.autodoc", diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 8f8dcc37489..6eac8cefb2b 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -7,9 +7,47 @@ MkDocs, Docusaurus and a variety of other tools. Here are minimal configuration examples for some common tools, with more coming soon. -.. toctree:: - :maxdepth: 2 - :caption: Supported doctools +.. info-card:: + + .. grid-item:: + :columns: 7 + + :doc:`/intro/mkdocs` is a powerful documentation framework on top of MkDocs. + + + .. grid-item:: + :columns: 2 + + Formats: + + Language: + + .. grid-item:: + :columns: 3 + + :tags-primary:`md` + + :tags-success:`python` + +.. info-card:: + + .. grid-item:: + :columns: 7 + + :doc:`/intro/sphinx` is a powerful documentation generator that has many features for writing technical documentation. + + .. grid-item:: + :columns: 2 + + Formats: + + Language: + + .. grid-item:: + :columns: 3 + + :tags-primary:`rst, md` + + :tags-success:`python` + - Sphinx - Material for Mkdocs diff --git a/requirements/docs.in b/requirements/docs.in index e5f406b6cb7..029c6c9981c 100644 --- a/requirements/docs.in +++ b/requirements/docs.in @@ -8,6 +8,7 @@ sphinx_rtd_theme==2.1.0rc1 sphinx-tabs sphinx-intl sphinx-design +sphinx-design-elements sphinx-multiproject # RTD deps :) From 925201cbaa76493b0b20590053deb7693141fb0e Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 5 Sep 2024 18:17:11 +0200 Subject: [PATCH 21/29] Update deps --- requirements/docs.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/requirements/docs.txt b/requirements/docs.txt index 3a33bec154e..874483412b7 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -122,6 +122,10 @@ sphinx-autobuild==2024.4.16 sphinx-copybutton==0.5.2 # via -r requirements/docs.in sphinx-design==0.6.1 + # via + # -r requirements/docs.in + # sphinx-design-elements +sphinx-design-elements==0.2.1 # via -r requirements/docs.in sphinx-hoverxref==1.4.0 # via -r requirements/docs.in From 846e0233d8f6752c0d46819690e18cb6a44d1a7f Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Tue, 10 Sep 2024 15:44:49 +0200 Subject: [PATCH 22/29] Alternate layout using only sphinx-design, with clickable cards --- docs/user/intro/doctools.rst | 50 +++++++++++------------------------- docs/user/intro/mkdocs.rst | 3 +++ 2 files changed, 18 insertions(+), 35 deletions(-) diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 6eac8cefb2b..3aabb75689f 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -7,47 +7,27 @@ MkDocs, Docusaurus and a variety of other tools. Here are minimal configuration examples for some common tools, with more coming soon. -.. info-card:: +.. grid:: 2 - .. grid-item:: - :columns: 7 + .. grid-item-card:: Material for MkDocs + :link: /intro/mkdocs.html - :doc:`/intro/mkdocs` is a powerful documentation framework on top of MkDocs. + Material for MkDocs is a powerful documentation framework on top of MkDocs. + Supported formats + :bdg-success:`md` + Written in + :bdg-info:`python` - .. grid-item:: - :columns: 2 - Formats: + .. grid-item-card:: Sphinx + :link: /intro/sphinx.html - Language: + Sphinx is a powerful documentation generator that has many features for writing technical documentation. - .. grid-item:: - :columns: 3 - - :tags-primary:`md` - - :tags-success:`python` - -.. info-card:: - - .. grid-item:: - :columns: 7 - - :doc:`/intro/sphinx` is a powerful documentation generator that has many features for writing technical documentation. - - .. grid-item:: - :columns: 2 - - Formats: - - Language: - - .. grid-item:: - :columns: 3 - - :tags-primary:`rst, md` - - :tags-success:`python` + Supported formats + :bdg-success:`rst` :bdg-success:`md` + Written in + :bdg-info:`python` diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index a6884eac9a4..87067951b2a 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -1,3 +1,6 @@ + +.. _material: + Material for MkDocs =================== From ed52f953b6a26e8ad90c605fb1ee17dc39f194b1 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 19 Sep 2024 17:49:50 +0200 Subject: [PATCH 23/29] Add language and markup info the main pages --- docs/user/intro/doctools.rst | 6 ++---- docs/user/intro/mkdocs.rst | 9 +++++++-- docs/user/intro/sphinx.rst | 10 ++++++---- 3 files changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 3aabb75689f..5720a1483c9 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -10,7 +10,7 @@ with more coming soon. .. grid:: 2 .. grid-item-card:: Material for MkDocs - :link: /intro/mkdocs.html + :link: mkdocs.html Material for MkDocs is a powerful documentation framework on top of MkDocs. @@ -21,7 +21,7 @@ with more coming soon. .. grid-item-card:: Sphinx - :link: /intro/sphinx.html + :link: sphinx.html Sphinx is a powerful documentation generator that has many features for writing technical documentation. @@ -29,5 +29,3 @@ with more coming soon. :bdg-success:`rst` :bdg-success:`md` Written in :bdg-info:`python` - - diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index 87067951b2a..f21676367b1 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -7,8 +7,9 @@ Material for MkDocs .. meta:: :description lang=en: Hosting Material for MkDocs sites on Read the Docs. -MkDocs is a fast, simple static site generator that's geared towards building project documentation. -Material for MkDocs is a powerful documentation framework on top of MkDocs. +`MkDocs`_ is a fast, simple static site generator that's geared towards building project documentation. +`Material for MkDocs`_ is a powerful documentation framework on top of MkDocs. +Mkdocs is written in Python, and supports documentation written in Markdown. .. note:: @@ -35,6 +36,10 @@ specifying a python toolchain on Ubuntu, defining the location of the installati mkdocs: configuration: mkdocs.yml +.. _MkDocs: https://www.mkdocs.org/ +.. _Material for MkDocs: https://squidfunk.github.io/mkdocs-material + + Quick start ----------- diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst index 94a4c5e1b9e..0ab1a4faadf 100644 --- a/docs/user/intro/sphinx.rst +++ b/docs/user/intro/sphinx.rst @@ -4,8 +4,9 @@ Sphinx .. meta:: :description lang=en: Hosting Sphinx documentation on Read the Docs. -Sphinx is a powerful documentation generator that +`Sphinx`_ is a powerful documentation generator that has many features for writing technical documentation. +Sphinx is written in Python, and supports documentation written in reStructuredText and Markdown. Minimal configuration required to build an existing Sphinx project on Read the Docs looks like this, specifying a python 3.x toolchain on Ubuntu, using the built-in :ref:`mkdocs ` command, @@ -29,6 +30,8 @@ and defining the location of the installation requirements: install: - requirements: requirements.txt +.. _Sphinx: https://www.sphinx-doc.org + Quick start ----------- @@ -94,7 +97,7 @@ If you're using a different theme, enable :doc:`Server side search Date: Thu, 19 Sep 2024 18:02:19 +0200 Subject: [PATCH 24/29] Revert unused dependencies --- requirements/docs.in | 1 - requirements/docs.txt | 4 ---- 2 files changed, 5 deletions(-) diff --git a/requirements/docs.in b/requirements/docs.in index 029c6c9981c..e5f406b6cb7 100644 --- a/requirements/docs.in +++ b/requirements/docs.in @@ -8,7 +8,6 @@ sphinx_rtd_theme==2.1.0rc1 sphinx-tabs sphinx-intl sphinx-design -sphinx-design-elements sphinx-multiproject # RTD deps :) diff --git a/requirements/docs.txt b/requirements/docs.txt index ea24fce8a95..5248e327d48 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -122,10 +122,6 @@ sphinx-autobuild==2024.9.3 sphinx-copybutton==0.5.2 # via -r requirements/docs.in sphinx-design==0.6.1 - # via - # -r requirements/docs.in - # sphinx-design-elements -sphinx-design-elements==0.2.1 # via -r requirements/docs.in sphinx-hoverxref==1.4.1 # via -r requirements/docs.in From 7af702334259f77a049944fc3f3df8455979d6b1 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 19 Sep 2024 18:18:20 +0200 Subject: [PATCH 25/29] Revert unused dependencies --- docs/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index a846e12a41b..71446013a2e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,7 +25,6 @@ # "notfound.extension", "sphinx_copybutton", "sphinx_design", - "sphinx_design_elements", "sphinx_tabs.tabs", "sphinx-prompt", "sphinx.ext.autodoc", From 3f46052c33108f6d87cb5157a744f49fdc004c80 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 23 Sep 2024 12:16:15 +0200 Subject: [PATCH 26/29] Apply suggestions from code review --- docs/user/intro/mkdocs.rst | 4 ++-- docs/user/intro/sphinx.rst | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index 5eaef520921..a6357a98300 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -182,10 +182,10 @@ Edit ``readthedocs.css`` to so that the font in the :ref:`flyout-menu:Addons fly Example repository and demo --------------------------- -Example repo:: +Example repository https://github.com/readthedocs/test-builds/tree/mkdocs-material -Demo:: +Demo https://test-builds.readthedocs.io/en/mkdocs-material/ Further reading diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst index 5e735dc9610..d5a0eea5fc7 100644 --- a/docs/user/intro/sphinx.rst +++ b/docs/user/intro/sphinx.rst @@ -97,7 +97,7 @@ If you're using a different theme, enable :doc:`Server side search Date: Mon, 23 Sep 2024 12:19:32 +0200 Subject: [PATCH 27/29] Use the full feature branch for now --- docs/user/intro/sphinx.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst index d5a0eea5fc7..54fe9d1ba34 100644 --- a/docs/user/intro/sphinx.rst +++ b/docs/user/intro/sphinx.rst @@ -152,10 +152,10 @@ Example repository and demo --------------------------- Example repository - https://github.com/readthedocs/test-builds/tree/sphinx-7.0.x + https://github.com/readthedocs/test-builds/tree/full-feature Demo - https://test-builds.readthedocs.io/en/sphinx-7.0.x + https://test-builds.readthedocs.io/en/full-feature Further reading --------------- From 06c0c1eb14400745d89fc7b0c518f45a3a795aba Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 23 Sep 2024 12:20:13 +0200 Subject: [PATCH 28/29] Style --- docs/user/intro/sphinx.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst index 54fe9d1ba34..b31ea2a1638 100644 --- a/docs/user/intro/sphinx.rst +++ b/docs/user/intro/sphinx.rst @@ -45,7 +45,7 @@ Quick start Configuring Sphinx and Read the Docs addons --------------------------------------------------------- +------------------------------------------- For optimal integration with Read the Docs, make the optional following configuration changes to your Spinx config. From eb71007be8c6261cdf2d67945c3b44d1e3f3667a Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 23 Sep 2024 12:23:22 +0200 Subject: [PATCH 29/29] Comment addons flyout section for now --- docs/user/intro/sphinx.rst | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst index b31ea2a1638..71b3e8bf3bd 100644 --- a/docs/user/intro/sphinx.rst +++ b/docs/user/intro/sphinx.rst @@ -101,21 +101,27 @@ If you're using a different theme, enable :doc:`Server side search `__, the :ref:`flyout-menu:Addons flyout menu` is already fully integrated. + Integrate the Read the Docs version menu into your site navigation + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You *may* need to set `flyout_display` to `hidden `_ in your ``conf.py`` so as not to display two identical menus: + If you're using the `Read the Docs Sphinx Theme `__, the :ref:`flyout-menu:Addons flyout menu` is already fully integrated. -.. code-block:: py - :caption: conf.py + You *may* need to set `flyout_display` to `hidden `_ in your ``conf.py`` so as not to display two identical menus: + + .. code-block:: py + :caption: conf.py - html_theme_options = { - "flyout_display": "hidden", - } + html_theme_options = { + "flyout_display": "hidden", + } -If you're using a different theme, the flyout menu will display in the default bottom right side of your docs. + If you're using a different theme, the flyout menu will display in the default bottom right side of your docs. Using Markdown with Sphinx --------------------------