Merge pull request #8440 from readthedocs/docs-misc-enhancements

Docs miscellaneous enhancements
readthedocs · Aug 24, 2021 · 407dffe · 407dffe
2 parents 20f808b + 53e7df1
commit 407dffe
Show file tree

Hide file tree

Showing 4 changed files with 27 additions and 86 deletions.
diff --git a/docs/guides/deprecating-content.rst b/docs/guides/deprecating-content.rst
@@ -78,12 +78,12 @@ This won't hide results from that page, but it will give priority to results fro
 
 .. TODO: mention search.ignore when it's implemented.
 
-
 .. tip::
 
-   If you are using Sphinx with reStructuredText,
-   you can make use of some :doc:`directives <sphinx:usage/restructuredtext/directives>`
-   like ``warning``, ``deprecated``, ``versionchanged`` to warn your users about deprecated content.
+   You can make use of Sphinx :doc:`directives <sphinx:usage/restructuredtext/directives>`
+   (like ``warning``, ``deprecated``, ``versionchanged``)
+   or MkDocs `admonitions <https://python-markdown.github.io/extensions/admonition/>`_
+   to warn your users about deprecated content.
 
 Moving and deleting pages
 -------------------------

diff --git a/docs/guides/intersphinx.rst b/docs/guides/intersphinx.rst
@@ -1,7 +1,8 @@
 Link to Other Projects' Documentation With Intersphinx
 ======================================================
 
-You may be familiar with using the :ref:`:ref: role <sphinx:ref-role>` to link to any location of your docs.
+You may be familiar with using the :ref:`:ref: role <sphinx:ref-role>` to
+:doc:`link to any location of your docs </guides/cross-referencing-with-sphinx>`.
 It helps you to keep all links within your docs up to date and warns you if a reference target moves or changes
 so you can ensure that your docs don't have broken cross-references.
 
@@ -46,14 +47,27 @@ And use the ``intersphinx_mapping`` configuration to indicate the name and link
    }
 
 
-Now we can use the ``sphinx`` name with a cross-reference role:
+Now you can use the ``sphinx`` name with a cross-reference role:
 
-.. code:: rst
+.. tabs::
 
-   - :ref:`sphinx:ref-role`
-   - :ref:`:ref: role <sphinx:ref-role>`
-   - :doc:`sphinx:usage/extensions/intersphinx`
-   - :doc:`Intersphinx <sphinx:usage/extensions/intersphinx>`
+   .. tab:: reStructuredText
+
+      .. code-block:: rst
+
+         - :ref:`sphinx:ref-role`
+         - :ref:`:ref: role <sphinx:ref-role>`
+         - :doc:`sphinx:usage/extensions/intersphinx`
+         - :doc:`Intersphinx <sphinx:usage/extensions/intersphinx>`
+
+   .. tab:: MyST (Markdown)
+
+      .. code-block:: md
+
+         - {ref}`sphinx:ref-role`
+         - {ref}`:ref: role <sphinx:ref-role>`
+         - {doc}`sphinx:usage/extensions/intersphinx`
+         - {doc}`Intersphinx <sphinx:usage/extensions/intersphinx>`
 
 Result:
 
@@ -65,7 +79,8 @@ Result:
 .. note::
 
    You can get the targets used in Intersphinx by inspecting the source file of the project or
-   using `this utility <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#showing-all-links-of-an-intersphinx-mapping-file>`__ provided by Intersphinx:
+   using `this utility <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#showing-all-links-of-an-intersphinx-mapping-file>`__
+   provided by Intersphinx:
 
    .. prompt:: bash $
 

diff --git a/docs/guides/mkdocs-old-versions.rst b/docs/guides/mkdocs-old-versions.rst
diff --git a/docs/guides/tools.rst b/docs/guides/tools.rst
@@ -12,7 +12,6 @@ whether that is Sphinx or MkDocs.
    intersphinx
    jupyter
    manage-translations
-   mkdocs-old-versions
    pdf-non-ascii-languages
    remove-edit-buttons
    vcs