Investigating moving some tutorials to Tools, and adding more tools

docs/user/guides/canonical-urls.rst

@@ -9,7 +9,7 @@ please refer to :doc:`/guides/custom-domains`.
 Sphinx
 ~~~~~~
 
-If you are using :doc:`Sphinx </intro/getting-started-with-sphinx>`,
+If you are using :doc:`Sphinx </tools/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 </intro/getting-started-with-mkdocs>` we do not define your canonical domain automatically,
+For :doc:`MkDocs </tools/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:

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:

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 </intro/getting-started-with-sphinx>`.
+    .. note:: Warning banners are available only for :doc:`Sphinx projects </tools/sphinx>`.
 
 .. seealso::
 

docs/user/tools/index.rst

@@ -0,0 +1,5 @@
+Supported doc tools
+======================
+
+You can use a number of documentation tools on RTD.
+

docs/user/intro/getting-started-with-mkdocs.rst → 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 </intro/getting-started-with-sphinx>`,
+    However, Read the Docs also supports :doc:`Sphinx </tools/sphinx>`,
     another tool for writing and building documentation.
 
 

docs/user/intro/getting-started-with-sphinx.rst → 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 <intro/getting-started-with-sphinx:Using Markdown with Sphinx>`
+* You can use reStructuredText or :ref:`Markdown <tools/sphinx:Using Markdown with Sphinx>`
   to write documentation
 * An extensive system of cross-referencing code and documentation
 * Syntax highlighted code samples

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