From 4043094bb71d63a13be4f0bfb9ba367669dc0f93 Mon Sep 17 00:00:00 2001 From: Sam Date: Mon, 23 Sep 2024 12:34:42 +0200 Subject: [PATCH] Add list of supported tools (#11547) * Fix indent * Noodling on doctools * Pre-commit * Remove mkdocs getting started guide * Typo * Skip jsdoc for now * Add clarity on mkdocs vs material * link fix * WIP * Review feedback * Remove Getting Started with Sphinx * Remove links as well * Some updates to Sphinx and MkDocs pages * Directive not installed * WIP * Shorter! * Add canonical url for sphinx * Add see also * Complete instructions * Add test card display * Update deps * Alternate layout using only sphinx-design, with clickable cards * Add language and markup info the main pages * Revert unused dependencies * Revert unused dependencies * Apply suggestions from code review * Use the full feature branch for now * Style * Comment addons flyout section for now --------- Co-authored-by: Manuel Kaufmann --- common | 2 +- docs/user/index.rst | 5 +- docs/user/intro/doctools.rst | 31 +++ .../intro/getting-started-with-mkdocs.rst | 87 -------- .../intro/getting-started-with-sphinx.rst | 119 ----------- docs/user/intro/mkdocs.rst | 200 ++++++++++++++++++ docs/user/intro/sphinx.rst | 174 +++++++++++++++ docs/user/tutorials/index.rst | 8 +- 8 files changed, 413 insertions(+), 213 deletions(-) create mode 100644 docs/user/intro/doctools.rst delete mode 100644 docs/user/intro/getting-started-with-mkdocs.rst delete mode 100644 docs/user/intro/getting-started-with-sphinx.rst create mode 100644 docs/user/intro/mkdocs.rst create mode 100644 docs/user/intro/sphinx.rst diff --git a/common b/common index 4b5818fcd4e..c766aa84a01 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit 4b5818fcd4ecb5348b3f64f79bf2f91deba80e1e +Subproject commit c766aa84a01b74d83c5fac061d92e31d512df99f diff --git a/docs/user/index.rst b/docs/user/index.rst index c5ac5cca7d9..4f339f66773 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -7,8 +7,9 @@ Read the Docs: documentation simplified :caption: Getting started /tutorial/index - /intro/getting-started-with-sphinx - /intro/getting-started-with-mkdocs + /intro/doctools + /intro/mkdocs + /intro/sphinx /intro/add-project /examples diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst new file mode 100644 index 00000000000..5720a1483c9 --- /dev/null +++ b/docs/user/intro/doctools.rst @@ -0,0 +1,31 @@ +Supported tools +=============== + +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. + +.. grid:: 2 + + .. grid-item-card:: Material for MkDocs + :link: mkdocs.html + + Material for MkDocs is a powerful documentation framework on top of MkDocs. + + Supported formats + :bdg-success:`md` + Written in + :bdg-info:`python` + + + .. grid-item-card:: Sphinx + :link: sphinx.html + + Sphinx is a powerful documentation generator that has many features for writing technical documentation. + + Supported formats + :bdg-success:`rst` :bdg-success:`md` + Written in + :bdg-info:`python` 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 9f952e4db9f..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/add-project` 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:`adding a project `. - -.. _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/getting-started-with-sphinx.rst b/docs/user/intro/getting-started-with-sphinx.rst deleted file mode 100644 index 3ed44e7bcd7..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/add-project` 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:`adding a project `. - -.. 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/ diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst new file mode 100644 index 00000000000..a6357a98300 --- /dev/null +++ b/docs/user/intro/mkdocs.rst @@ -0,0 +1,200 @@ + +.. _material: + +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 written in Python, and supports documentation written in Markdown. + +.. note:: + + This page is explicitly about Material for MkDocs. We're working on a guide for plain MkDocs as well. + +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-24.04 + tools: + python: "3" + + python: + install: + - requirements: requirements.txt + + mkdocs: + configuration: mkdocs.yml + +.. _MkDocs: https://www.mkdocs.org/ +.. _Material for MkDocs: https://squidfunk.github.io/mkdocs-material + + +Quick start +----------- + +- If you have an existing Material for MkDocs project you want to host on Read the Docs, check out our :doc:`/intro/add-project` guide. + +- If you're new to Material for MkDocs, check out the official `Getting started with Material for MkDocs`_ guide. + +.. _Getting started with Material for MkDocs: https://squidfunk.github.io/mkdocs-material/getting-started/ + +Configuring Material for MkDocs and Read the Docs addons +-------------------------------------------------------- + +For optimal integration with Read the Docs, make the optional following configuration changes to your Material for MkDocs config. + +.. contents:: + :depth: 1 + :local: + :backlinks: none + +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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To configure your site to use :doc:`Read the Docs search ` instead of the default search: + +#. Add the following block of JavaScript: + + .. 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 your MkDocs configuration: + + .. code-block:: yaml + :caption: mkdocs.yml + + extra_javascript: + - javascript/readthedocs.js + + +Integrate the Read the Docs version menu into your site navigation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To integrate the :ref:`flyout-menu:Addons flyout menu` 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 your MkDocs configuration: + + .. code-block:: yaml + :caption: mkdocs.yml + + extra_javascript: + - javascript/readthedocs.js + +Adjust the flyout menu font size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Edit ``readthedocs.css`` to so that the font in the :ref:`flyout-menu:Addons flyout menu` matches the theme better. + +.. code-block:: css + :caption: readthedocs.css: + + :root { + /* Reduce Read the Docs' flyout font a little bit */ + --readthedocs-flyout-font-size: 0.7rem; + + /* Reduce Read the Docs' notification font a little bit */ + --readthedocs-notification-font-size: 0.8rem; + + /* This customization is not yet perfect because we can't change the `line-height` yet. */ + /* See https://github.com/readthedocs/addons/issues/197 */ + --readthedocs-search-font-size: 0.7rem; + } + +Example repository and demo +--------------------------- + +Example repository + https://github.com/readthedocs/test-builds/tree/mkdocs-material + +Demo + https://test-builds.readthedocs.io/en/mkdocs-material/ + +Further reading +--------------- + +* `Material for MkDocs documentation`_ +* `Markdown syntax guide`_ +* `Writing your docs with MkDocs`_ + +.. _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/ diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst new file mode 100644 index 00000000000..71b3e8bf3bd --- /dev/null +++ b/docs/user/intro/sphinx.rst @@ -0,0 +1,174 @@ +Sphinx +====== + +.. 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. +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, +and defining the location of the installation requirements: + + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + + build: + os: ubuntu-24.04 + tools: + python: "3" + + sphinx: + configuration: docs/conf.py + + python: + install: + - requirements: requirements.txt + +.. _Sphinx: https://www.sphinx-doc.org + +Quick start +----------- + +- If you have an existing Sphinx project you want to host on Read the Docs, check out our :doc:`/intro/add-project` 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 + +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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you're using the `Read the Docs Sphinx Theme `__, +: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", + ] + + +.. TODO: adapt and uncomment this section. + We've changed `flyout_display` to be `hidden` by default; + If people want to use the integrated version of it, they should declare it as `attached`. + However, as we have the version/language selectors now, + we want to promote that more and keep the Addons flyout enabled by default. + + 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 +-------------------------- + +You can use `Markdown using MyST`_ and reStructuredText in the same Sphinx project. +We support this natively on Read the Docs, and you can also use locally by installing ``myst-parser``: + +.. 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. + +.. 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 +--------------------------- + +Example repository + https://github.com/readthedocs/test-builds/tree/full-feature + +Demo + https://test-builds.readthedocs.io/en/full-feature + +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/ diff --git a/docs/user/tutorials/index.rst b/docs/user/tutorials/index.rst index d72b5b03c37..c66dd7bc097 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:`/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. -⏩️ :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. @@ -37,8 +37,8 @@ Tutorials :hidden: /tutorial/index - /intro/getting-started-with-sphinx - /intro/getting-started-with-mkdocs + /intro/sphinx + /intro/mkdocs /intro/add-project /config-file/index /examples