diff --git a/docs/conf.py b/docs/conf.py index e2747e4c4ad..00190c5dcdd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,6 +22,7 @@ "multiproject", "myst_parser", "notfound.extension", + "sphinx_copybutton", "sphinx_design", "sphinx_search.extension", "sphinx_tabs.tabs", diff --git a/docs/user/build-customization.rst b/docs/user/build-customization.rst index b3cf2c52602..5ca88f07dd8 100644 --- a/docs/user/build-customization.rst +++ b/docs/user/build-customization.rst @@ -339,6 +339,8 @@ Take a look at the following example: configuration: docs/conf.py +.. _build_commands_introduction: + Override the build process -------------------------- diff --git a/docs/user/config-file/examples/README b/docs/user/config-file/examples/README new file mode 100644 index 00000000000..606d8da8b3d --- /dev/null +++ b/docs/user/config-file/examples/README @@ -0,0 +1,8 @@ +README + +What is config-file/examples for? + +To make maintenance easier, we are collecting all examples of configurations +used in documentation and on the website here. + +Future potential scenarios for leveraging this structure aren't decided. diff --git a/docs/user/config-file/examples/mkdocs/.readthedocs.yaml b/docs/user/config-file/examples/mkdocs/.readthedocs.yaml new file mode 100644 index 00000000000..c5587fb24a4 --- /dev/null +++ b/docs/user/config-file/examples/mkdocs/.readthedocs.yaml @@ -0,0 +1,19 @@ +# Read the Docs configuration file for MkDocs projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +mkdocs: + configuration: mkdocs.yml + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements.txt diff --git a/docs/user/config-file/examples/sphinx/.readthedocs.yaml b/docs/user/config-file/examples/sphinx/.readthedocs.yaml new file mode 100644 index 00000000000..4484bf0e72b --- /dev/null +++ b/docs/user/config-file/examples/sphinx/.readthedocs.yaml @@ -0,0 +1,31 @@ +# Read the Docs configuration file for Sphinx projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +# python: +# install: +# - requirements: docs/requirements.txt diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst index 5461ecaa390..77d6ae0d5f4 100644 --- a/docs/user/config-file/v2.rst +++ b/docs/user/config-file/v2.rst @@ -12,62 +12,18 @@ Below is an example YAML file which shows the most common configuration options: .. tab:: Sphinx - .. code:: yaml - - # .readthedocs.yaml - # Read the Docs configuration file - # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details - - # Required - version: 2 - - # Set the version of Python and other tools you might need - build: - os: ubuntu-22.04 - tools: - python: "3.11" - # You can also specify other tool versions: - # nodejs: "19" - # rust: "1.64" - # golang: "1.19" - - # Build documentation in the docs/ directory with Sphinx - sphinx: - configuration: docs/conf.py - - # If using Sphinx, optionally build your docs in additional formats such as PDF - # formats: - # - pdf - - # Optionally declare the Python requirements required to build your docs - python: - install: - - requirements: docs/requirements.txt + .. literalinclude:: /config-file/examples/sphinx/.readthedocs.yaml + :language: yaml + :linenos: + :caption: .readthedocs.yaml .. tab:: MkDocs - .. code:: yaml + .. literalinclude:: /config-file/examples/mkdocs/.readthedocs.yaml + :language: yaml + :linenos: + :caption: .readthedocs.yaml - # .readthedocs.yaml - # Read the Docs configuration file - # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details - - # Required - version: 2 - - # Set the version of Python and other tools you might need - build: - os: ubuntu-22.04 - tools: - python: "3.11" - - mkdocs: - configuration: mkdocs.yml - - # Optionally declare the Python requirements required to build your docs - python: - install: - - requirements: docs/requirements.txt Supported settings ------------------ diff --git a/docs/user/guides/pull-requests.rst b/docs/user/guides/pull-requests.rst index c4c001602e3..386cc13f6a2 100644 --- a/docs/user/guides/pull-requests.rst +++ b/docs/user/guides/pull-requests.rst @@ -14,6 +14,11 @@ If your account is already connected: #. Enable the :guilabel:`Build pull requests for this project` option #. Click on :guilabel:`Save` +.. tip:: + + Pull requests opened before enabling pull request builds will not trigger new builds automatically. + Push a new commit to the pull request to trigger its first build. + Privacy levels -------------- diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst new file mode 100644 index 00000000000..035cc3cb29c --- /dev/null +++ b/docs/user/guides/setup/configuration-file.rst @@ -0,0 +1,183 @@ +How to add a configuration file +=============================== + +As part of the initial set up for your Read the Docs site, +you need to create a **configuration file** called ``.readthedocs.yaml``. +The configuration file tells Read the Docs what specific settings to use for your project. + +This how-to guide covers: + +#. Where to put your configuration file. +#. What to put in the configuration file. +#. How to customize the configuration for your project. + +.. seealso:: + + :doc:`/tutorial/index`. + Following the steps in our tutorial will help you setup your first documentation project. + + +Where to put your configuration file +------------------------------------ + +The ``.readthedocs.yaml`` file should be placed in the top-most directory of your project's repository. +We will get to the contents of the file in the next steps. + +When you have changed the configuration file, +you need to commit and push the changes to your Git repository. +Read the Docs will then automatically find and use the configuration to build your project. + +.. note:: + + The Read the Docs configuration file is a `YAML`_ file. + YAML is a human-friendly data serialization language for all programming languages. + To learn more about the structure of these files, see the `YAML language overview`_. + +.. _YAML: https://yaml.org/ +.. _YAML language overview: https://yaml.org/spec/1.2.2/#chapter-1-introduction-to-yaml + +.. _howto_templates: + +Getting started with a template +------------------------------- + +Here are some configuration file examples to help you get started. +Pick an example based on the tool that your project is using, +copy its contents to ``.readthedocs.yaml`` and add the file to your Git repository. + +.. tabs:: + + .. tab:: Sphinx + + If your project uses Sphinx, + we offer a special builder optimized for Sphinx projects. + + .. literalinclude:: /config-file/examples/sphinx/.readthedocs.yaml + :language: yaml + :linenos: + :caption: .readthedocs.yaml + + + .. tab:: MkDocs + + If your project uses MkDocs, + we offer a special builder optimized for MkDocs projects. + + .. literalinclude:: /config-file/examples/mkdocs/.readthedocs.yaml + :language: yaml + :linenos: + :caption: .readthedocs.yaml + +Editing the template +-------------------- + +Now that you have a ``.readthedocs.yaml`` file added to your Git repository, +you should see Read the Docs trying to build your project with the configuration file. +The configuration file probably needs some adjustments to accommodate exactly your project setup. + +.. note:: + + If you added the configuration file in a separate branch, + you may have to activate a :doc:`version ` for that branch. + + If you have added the file in a pull request, + you should enable :doc:`pull request builds `. + +Skip: file header and comments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are some parts of the templates that you can leave in place: + +Comments + We added comments that explain the configuration options and optional features. + These lines begin with a ``#``. + +Commented out features + We use the ``#`` in front of some popular configuration options. + They are there as examples, + which you can choose to enable, delete or save for later. + +``version`` key + The version key tells the system how to read the rest of the configuration file. + The current and only supported version is **version 2**. + + +Adjust: ``build.os`` +~~~~~~~~~~~~~~~~~~~~ + +In our examples, +we are using Read the Docs' custom image based on the latest Ubuntu release. +Package versions in these images will not change drastically, +though will receive periodic security updates. + +You should pay attention to this field if your project needs to build on an older version of Ubuntu, +or in the future when you need features from a newer Ubuntu. + +.. seealso:: + + :ref:`config-file/v2:build.os` + Configuration file reference with all values possible for ``build.os``. + + +Adjust: Python configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are using Python in your builds, +you should define the Python version in ``build.tools.python``. + +The ``python`` key contains a list of sub-keys, +specifying the requirements to install. + +- Use ``python.install.package`` to install the project itself as a Python package using pip +- Use ``python.install.requirements`` to install packages from a requirements file +- Use ``build.jobs`` to install packages using Poetry or PDM + +.. seealso:: + + :ref:`config-file/v2:build.tools.python` + Configuration file reference with all Python versions available for ``build.tools.python``. + + :ref:`config-file/v2:python` + Configuration file reference for configuring the Python environment activated by ``build.tools.python``. + +Adjust: Sphinx and MkDocs version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are using either the ``sphinx`` or ``mkdocs`` builder, +then Sphinx or MkDocs will be installed automatically in its latest version. + +But we recommend that you specify the version that your documentation project uses. +The ``requirements`` key is a file path that points to a text (``.txt``) file +that lists the Python packages you want Read the Docs to install. + +.. seealso:: + + :ref:`guides/reproducible-builds:Use a requirements file for Python dependencies` + This guide explains how to specify Python requirements, + such as the version of Sphinx or MkDocs. + + :ref:`config-file/v2:sphinx` + Configuration file reference for configuring the Sphinx builder. + + :ref:`config-file/v2:mkdocs` + Configuration file reference for configuring the MkDocs builder. + +Next steps +---------- + +There are more configuration options that the ones mentioned in this guide. + +After you add a configuration file your Git repository, +and you can see that Read the Docs is building your documentation using the file, +you should have a look at the complete configuration file reference for options that might apply to your project. + +.. seealso:: + + :doc:`/config-file/v2`. + The complete list of all possible ``.readthedocs.yaml`` settings, + including the optional settings not covered in on this page. + + :doc:`/build-customization` + Are familiar with running a command line? + Perhaps there are special commands that you know you want Read the Docs to run. + Read this guide and learn more about how you add your own commands to ``.readthedocs.yaml``. diff --git a/docs/user/guides/setup/index.rst b/docs/user/guides/setup/index.rst index 46ab43c08c0..228231bee9d 100644 --- a/docs/user/guides/setup/index.rst +++ b/docs/user/guides/setup/index.rst @@ -14,6 +14,11 @@ The following how-to guides help you solve common tasks and challenges in the se If you are connecting a Git repository from another provider (for instance Gitea or Codeberg), this guide tells you how to add and configure the webhook **manually**. +⏩ :doc:`Adding a configuration file ` + To build your documentation project, + you need to add a ``.readthedocs.yaml`` configuration file. + This guide gets you started. + ⏩️ :doc:`Managing custom domains ` Hosting your documentation using your own domain name, such as ``docs.example.com``. @@ -45,6 +50,7 @@ The following how-to guides help you solve common tasks and challenges in the se Connecting your Read the Docs account to your Git provider Configuring a Git repository automatically Configuring a Git repository manually + Adding a configuration file Managing custom domains Managing subprojects Hiding a version diff --git a/requirements/docs.in b/requirements/docs.in index 5f2f019a1d6..33a3c2dc395 100644 --- a/requirements/docs.in +++ b/requirements/docs.in @@ -18,6 +18,7 @@ sphinxcontrib-httpdomain sphinx-prompt sphinx-autobuild sphinxext-opengraph +sphinx-copybutton # Markdown myst_parser diff --git a/requirements/docs.txt b/requirements/docs.txt index 46860f3a706..3ea07d520d2 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -96,6 +96,7 @@ sphinx==6.2.1 # -r requirements/docs.in # myst-parser # sphinx-autobuild + # sphinx-copybutton # sphinx-design # sphinx-hoverxref # sphinx-intl @@ -109,6 +110,8 @@ sphinx==6.2.1 # sphinxext-opengraph sphinx-autobuild==2021.3.14 # via -r requirements/docs.in +sphinx-copybutton==0.5.2 + # via -r requirements/docs.in sphinx-design==0.4.1 # via -r requirements/docs.in sphinx-hoverxref==1.3.0