From 5434bba5905919cfca6a57166a90c29c887dca9e Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Wed, 8 May 2024 17:26:31 +0200 Subject: [PATCH] WIP --- docs/user/guides/canonical-urls.rst | 4 ++-- docs/user/index.rst | 11 +++++++++-- docs/user/pull-requests.rst | 2 +- docs/user/tools/index.rst | 5 +++++ .../mkdocs.rst} | 2 +- .../sphinx.rst} | 2 +- docs/user/tutorials/index.rst | 8 ++++---- 7 files changed, 23 insertions(+), 11 deletions(-) create mode 100644 docs/user/tools/index.rst rename docs/user/{intro/getting-started-with-mkdocs.rst => tools/mkdocs.rst} (96%) rename docs/user/{intro/getting-started-with-sphinx.rst => tools/sphinx.rst} (97%) diff --git a/docs/user/guides/canonical-urls.rst b/docs/user/guides/canonical-urls.rst index 91e466646ff..bc421539c9f 100644 --- a/docs/user/guides/canonical-urls.rst +++ b/docs/user/guides/canonical-urls.rst @@ -9,7 +9,7 @@ please refer to :doc:`/guides/custom-domains`. Sphinx ~~~~~~ -If you are using :doc:`Sphinx `, +If you are using :doc:`Sphinx `, Read the Docs will automatically add a default value of the html_baseurl_ setting matching your canonical domain. If you are using a custom ``html_baseurl`` in your ``conf.py``, @@ -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 f190ae4cbae..3e91c88aa6f 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -8,11 +8,18 @@ Read the Docs: documentation simplified /tutorial/index /choosing-a-site - /intro/getting-started-with-sphinx - /intro/getting-started-with-mkdocs /intro/import-guide /examples +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Supported doctools + + /tools/index + /tools/sphinx + /tools/mkdocs + .. toctree:: :maxdepth: 2 :hidden: diff --git a/docs/user/pull-requests.rst b/docs/user/pull-requests.rst index 3590d64dd3d..d34a40cfdf1 100644 --- a/docs/user/pull-requests.rst +++ b/docs/user/pull-requests.rst @@ -28,7 +28,7 @@ Warning banner A warning banner is shown at the top of documentation pages to let readers know that this version isn't the main version for the project. - .. note:: Warning banners are available only for :doc:`Sphinx projects `. + .. note:: Warning banners are available only for :doc:`Sphinx projects `. .. seealso:: diff --git a/docs/user/tools/index.rst b/docs/user/tools/index.rst new file mode 100644 index 00000000000..e73a4e19123 --- /dev/null +++ b/docs/user/tools/index.rst @@ -0,0 +1,5 @@ +Supported doc tools +====================== + +You can use a number of documentation tools on RTD. + diff --git a/docs/user/intro/getting-started-with-mkdocs.rst b/docs/user/tools/mkdocs.rst similarity index 96% rename from docs/user/intro/getting-started-with-mkdocs.rst rename to docs/user/tools/mkdocs.rst index 150d07ccb30..4cf3ffdc637 100644 --- a/docs/user/intro/getting-started-with-mkdocs.rst +++ b/docs/user/tools/mkdocs.rst @@ -15,7 +15,7 @@ It has many great features including: .. note:: MkDocs is a great choice for building technical documentation. - However, Read the Docs also supports :doc:`Sphinx `, + However, Read the Docs also supports :doc:`Sphinx `, another tool for writing and building documentation. diff --git a/docs/user/intro/getting-started-with-sphinx.rst b/docs/user/tools/sphinx.rst similarity index 97% rename from docs/user/intro/getting-started-with-sphinx.rst rename to docs/user/tools/sphinx.rst index 48fb3b5c68d..bef9f1531b4 100644 --- a/docs/user/intro/getting-started-with-sphinx.rst +++ b/docs/user/tools/sphinx.rst @@ -9,7 +9,7 @@ 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 ` +* You can use reStructuredText or :ref:`Markdown ` to write documentation * An extensive system of cross-referencing code and documentation * Syntax highlighted code samples diff --git a/docs/user/tutorials/index.rst b/docs/user/tutorials/index.rst index bc04a479b3c..04823cabf86 100644 --- a/docs/user/tutorials/index.rst +++ b/docs/user/tutorials/index.rst @@ -9,12 +9,12 @@ 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:`/tools/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. -⏩️ :doc:`/intro/getting-started-with-mkdocs` +⏩️ :doc:`/tools/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. @@ -37,8 +37,8 @@ Tutorials :hidden: /tutorial/index - /intro/getting-started-with-sphinx - /intro/getting-started-with-mkdocs + /tools/sphinx + /tools/mkdocs /intro/import-guide /config-file/index /examples