From 1b3e201478694d02717bc441369e03aae03fea3e Mon Sep 17 00:00:00 2001 From: Nik Blanchet Date: Sun, 7 May 2023 12:01:38 -0700 Subject: [PATCH 01/31] WIP. Completed introduction and file location sections. --- docs/user/guides/creating-config-file.rst | 46 +++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/user/guides/creating-config-file.rst diff --git a/docs/user/guides/creating-config-file.rst b/docs/user/guides/creating-config-file.rst new file mode 100644 index 00000000000..dac027a2252 --- /dev/null +++ b/docs/user/guides/creating-config-file.rst @@ -0,0 +1,46 @@ +================================ +Creating your configuration file +================================ + +As part of the initial setup for your Read the Docs site, you need to create a +**configuration file** called ``.readthedocs.yaml``. + +The configuration file like a personalized guidebook that tells the platform +what specific settings for your project. Every project is unique, and by using +a configuration file, you can tailor the behavior of Read the Docs to match +your specific needs. + +This how-to guide covers +#. Where to put your configuration file +#. The required parts of your configuration file + +This should be enough to get you started! + +.. tip:: + + The complete list of all possible ``.readthedocs.yaml`` settings, including + the optional settings not covered in on this page, is found on + :doc:`the configuration file reference page `. + +#################################### +Where to put your configuration file +#################################### + +The ``.readthedocs.yaml`` file should be placed in the **root directory**. The +root directory is the top-most location of your repository. + +To make the file, navigate to your root directory and create a new +file with the name ``.readthedocs.yaml``. + +.. note:: + + The ``.`` at the beginning of the file indicates that the file is hidden. If + the file browser you are using is not configured to show hidden files, you + may not be able to see the file after you create it! If this happens, use + your favorite search engine to find instructions on showing hidden files for + your specific operating system. + +############################################# +The required parts of your configuration file +############################################# + From 063ad2a2d05c5171b93b13888f736cd9756e55f5 Mon Sep 17 00:00:00 2001 From: Nik Blanchet Date: Sun, 7 May 2023 12:08:04 -0700 Subject: [PATCH 02/31] WIP. Converted note admonition to a section. --- docs/user/guides/creating-config-file.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/user/guides/creating-config-file.rst b/docs/user/guides/creating-config-file.rst index dac027a2252..57b23d36a09 100644 --- a/docs/user/guides/creating-config-file.rst +++ b/docs/user/guides/creating-config-file.rst @@ -32,13 +32,17 @@ root directory is the top-most location of your repository. To make the file, navigate to your root directory and create a new file with the name ``.readthedocs.yaml``. -.. note:: +************************* +The config file is hidden +************************* - The ``.`` at the beginning of the file indicates that the file is hidden. If - the file browser you are using is not configured to show hidden files, you - may not be able to see the file after you create it! If this happens, use - your favorite search engine to find instructions on showing hidden files for - your specific operating system. +The ``.`` at the beginning of the file indicates that the file is hidden. If +the file browser you are using is not configured to show hidden files, you may +not be able to see the file after you create it! + +If you cannot see ``.readthedocs.yaml`` after creating it, use your favorite +search engine to find instructions on showing hidden files for your specific +operating system. ############################################# The required parts of your configuration file From 04ce49bc9857e91ccdcc1119a797c053d49d1042 Mon Sep 17 00:00:00 2001 From: Nik Blanchet Date: Sun, 7 May 2023 15:19:48 -0700 Subject: [PATCH 03/31] WIP. Began config file requirements. Pausing so Manuel can create a bulleted list explaining what the requirements actually are. --- docs/user/guides/creating-config-file.rst | 50 +++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/user/guides/creating-config-file.rst b/docs/user/guides/creating-config-file.rst index 57b23d36a09..a15a72b2368 100644 --- a/docs/user/guides/creating-config-file.rst +++ b/docs/user/guides/creating-config-file.rst @@ -48,3 +48,53 @@ operating system. The required parts of your configuration file ############################################# +The configuration file is a YAML file. YAML files are a "map": a collection of +key-value pairs that can be nested. This is not unlike a JSON file or ``dict`` +object in Python. + +This page won't explain the structure of YAML files, but many resources exist +online. + +*********** +File header +*********** + +As a best practice, begin your file by providing the following. + +#. The name of the file +#. A quick explanation of what the file is +#. A link to + :doc:`the configuration file reference page `. + +.. code-block:: yaml + :linenos: + + # .readthedocs.yaml + # Read the Docs configuration file + # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + # <--Remove this comment and leave this line blank--> + +************************************ +Version of configuration file schema +************************************ + +The version key tells the system how to read the rest of the configuration +file. The current and only supported version is **version 2**. + +.. code-block:: yaml + :linenos: + :lineno-start: 5 + + version: 2 + # <--Remove this comment and leave this line blank--> + +******************* +Python requirements +******************* + +The ``python`` key contains several sub-keys, but only one sub-key is required: +``requirements``. However, since ``requirements`` is required, ``python`` is +too. + +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. \ No newline at end of file From 70ac7e49c10d05817c041a06ee6c1ca674a4ae03 Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Wed, 7 Jun 2023 15:56:46 +0200 Subject: [PATCH 04/31] Apply suggestions from code review by @benjaoming and @agjohnson Co-authored-by: Anthony --- docs/user/guides/creating-config-file.rst | 37 +++++++++-------------- 1 file changed, 14 insertions(+), 23 deletions(-) diff --git a/docs/user/guides/creating-config-file.rst b/docs/user/guides/creating-config-file.rst index a15a72b2368..edd5cd10381 100644 --- a/docs/user/guides/creating-config-file.rst +++ b/docs/user/guides/creating-config-file.rst @@ -5,14 +5,17 @@ Creating your configuration file As part of the initial setup for your Read the Docs site, you need to create a **configuration file** called ``.readthedocs.yaml``. -The configuration file like a personalized guidebook that tells the platform -what specific settings for your project. Every project is unique, and by using -a configuration file, you can tailor the behavior of Read the Docs to match -your specific needs. +The configuration file is like a personalized guidebook that tells the platform what specific settings to use for your project. +By using a configuration file, +you can tailor the behavior of Read the Docs to match your project's specific needs. -This how-to guide covers -#. Where to put your configuration file -#. The required parts of your configuration file +In addition that that, +using a configuration file can capture important configuration options that might otherwise break in the future if left undefined. + +This how-to guide covers: + +#. Where to put your configuration file. +#. What to add to your configuration file. This should be enough to get you started! @@ -20,29 +23,17 @@ This should be enough to get you started! The complete list of all possible ``.readthedocs.yaml`` settings, including the optional settings not covered in on this page, is found on - :doc:`the configuration file reference page `. + :doc:`the configuration file reference page `. #################################### Where to put your configuration file #################################### -The ``.readthedocs.yaml`` file should be placed in the **root directory**. The -root directory is the top-most location of your repository. - -To make the file, navigate to your root directory and create a new -file with the name ``.readthedocs.yaml``. - -************************* -The config file is hidden -************************* +The ``.readthedocs.yaml`` file should be placed in the top-most directory of your project's repository. -The ``.`` at the beginning of the file indicates that the file is hidden. If -the file browser you are using is not configured to show hidden files, you may -not be able to see the file after you create it! +Add a new file with the exact name ``.readthedocs.yaml`` in the repository's root directory. +We will get to the contents of the file in a moment. -If you cannot see ``.readthedocs.yaml`` after creating it, use your favorite -search engine to find instructions on showing hidden files for your specific -operating system. ############################################# The required parts of your configuration file From dae85dcb777e1d0d51151fd3dbfb09842a363b4c Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 16:03:34 +0200 Subject: [PATCH 05/31] Make it build --- .../configuration-file.rst} | 22 +++++++++---------- docs/user/guides/setup/index.rst | 6 +++++ 2 files changed, 17 insertions(+), 11 deletions(-) rename docs/user/guides/{creating-config-file.rst => setup/configuration-file.rst} (93%) diff --git a/docs/user/guides/creating-config-file.rst b/docs/user/guides/setup/configuration-file.rst similarity index 93% rename from docs/user/guides/creating-config-file.rst rename to docs/user/guides/setup/configuration-file.rst index edd5cd10381..1003668b3dc 100644 --- a/docs/user/guides/creating-config-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -2,7 +2,7 @@ Creating your configuration file ================================ -As part of the initial setup for your Read the Docs site, you need to create a +As part of the initial setup for your Read the Docs site, you need to create a **configuration file** called ``.readthedocs.yaml``. The configuration file is like a personalized guidebook that tells the platform what specific settings to use for your project. @@ -20,10 +20,10 @@ This how-to guide covers: This should be enough to get you started! .. tip:: - - The complete list of all possible ``.readthedocs.yaml`` settings, including - the optional settings not covered in on this page, is found on - :doc:`the configuration file reference page `. + + The complete list of all possible ``.readthedocs.yaml`` settings, including + the optional settings not covered in on this page, is found on + :doc:`the configuration file reference page `. #################################### Where to put your configuration file @@ -43,7 +43,7 @@ The configuration file is a YAML file. YAML files are a "map": a collection of key-value pairs that can be nested. This is not unlike a JSON file or ``dict`` object in Python. -This page won't explain the structure of YAML files, but many resources exist +This page won't explain the structure of YAML files, but many resources exist online. *********** @@ -54,8 +54,8 @@ As a best practice, begin your file by providing the following. #. The name of the file #. A quick explanation of what the file is -#. A link to - :doc:`the configuration file reference page `. +#. A link to + :doc:`the configuration file reference page `. .. code-block:: yaml :linenos: @@ -69,7 +69,7 @@ As a best practice, begin your file by providing the following. Version of configuration file schema ************************************ -The version key tells the system how to read the rest of the configuration +The version key tells the system how to read the rest of the configuration file. The current and only supported version is **version 2**. .. code-block:: yaml @@ -84,8 +84,8 @@ Python requirements ******************* The ``python`` key contains several sub-keys, but only one sub-key is required: -``requirements``. However, since ``requirements`` is required, ``python`` is +``requirements``. However, since ``requirements`` is required, ``python`` is too. 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. \ No newline at end of file +that lists the Python packages you want Read the Docs to install. diff --git a/docs/user/guides/setup/index.rst b/docs/user/guides/setup/index.rst index 46ab43c08c0..703dbf19974 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 ` + When setting up a new 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 From fcccd92394b4d93bd8a350f2d924b7d254c89d98 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 16:17:12 +0200 Subject: [PATCH 06/31] rtd's rst header coventions --- docs/user/guides/setup/configuration-file.rst | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index 1003668b3dc..63ce669742e 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -1,4 +1,3 @@ -================================ Creating your configuration file ================================ @@ -25,9 +24,9 @@ This should be enough to get you started! the optional settings not covered in on this page, is found on :doc:`the configuration file reference page `. -#################################### + Where to put your configuration file -#################################### +------------------------------------ The ``.readthedocs.yaml`` file should be placed in the top-most directory of your project's repository. @@ -35,9 +34,8 @@ Add a new file with the exact name ``.readthedocs.yaml`` in the repository's roo We will get to the contents of the file in a moment. -############################################# The required parts of your configuration file -############################################# +--------------------------------------------- The configuration file is a YAML file. YAML files are a "map": a collection of key-value pairs that can be nested. This is not unlike a JSON file or ``dict`` @@ -46,9 +44,8 @@ object in Python. This page won't explain the structure of YAML files, but many resources exist online. -*********** File header -*********** +~~~~~~~~~~~ As a best practice, begin your file by providing the following. @@ -65,9 +62,9 @@ As a best practice, begin your file by providing the following. # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details # <--Remove this comment and leave this line blank--> -************************************ + Version of configuration file schema -************************************ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The version key tells the system how to read the rest of the configuration file. The current and only supported version is **version 2**. @@ -79,9 +76,8 @@ file. The current and only supported version is **version 2**. version: 2 # <--Remove this comment and leave this line blank--> -******************* Python requirements -******************* +~~~~~~~~~~~~~~~~~~~ The ``python`` key contains several sub-keys, but only one sub-key is required: ``requirements``. However, since ``requirements`` is required, ``python`` is From 580fe2b4095e5eb43fd18180ad4b32d69e19e314 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 16:43:08 +0200 Subject: [PATCH 07/31] Header as how-to + shorten intro a bit more --- docs/user/guides/setup/configuration-file.rst | 21 +++++++++++-------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index 63ce669742e..38316684542 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -1,15 +1,18 @@ -Creating your configuration file -================================ +How to add a configuration file +=============================== -As part of the initial setup for your Read the Docs site, you need to create a -**configuration file** called ``.readthedocs.yaml``. +As part of the initial setup for your Read the Docs site, +you need to create a **configuration file** called ``.readthedocs.yaml``. -The configuration file is like a personalized guidebook that tells the platform what specific settings to use for your project. -By using a configuration file, -you can tailor the behavior of Read the Docs to match your project's specific needs. +The configuration file tells the platform what specific settings to use for your project. -In addition that that, -using a configuration file can capture important configuration options that might otherwise break in the future if left undefined. +.. TODO: This isn't really how-to content. We might want to add "Configuration as Code" or similar to our features in order to deal with this. +.. I have another PR open where this is added. + +.. By using a configuration file, +.. you can tailor the behavior of Read the Docs to match your project's specific needs. +.. In addition that that, +.. using a configuration file can capture important configuration options that might otherwise break in the future if left undefined. This how-to guide covers: From b1b9bb9dc8f408fa8d707d80b75588b84ff48dbb Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 16:48:50 +0200 Subject: [PATCH 08/31] YAML: Reference Wikipedia --- docs/user/guides/setup/configuration-file.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index 38316684542..47617f6650c 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -40,13 +40,15 @@ We will get to the contents of the file in a moment. The required parts of your configuration file --------------------------------------------- -The configuration file is a YAML file. YAML files are a "map": a collection of +The configuration file is a `YAML`_ file. YAML files are a "map": a collection of key-value pairs that can be nested. This is not unlike a JSON file or ``dict`` object in Python. This page won't explain the structure of YAML files, but many resources exist online. +.. _YAML: https://en.wikipedia.org/wiki/YAML + File header ~~~~~~~~~~~ From ff262536e0e9772a647303a501175aab6206b36c Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 17:05:41 +0200 Subject: [PATCH 09/31] Use sphinx-copybutton --- docs/conf.py | 1 + requirements/docs.in | 1 + requirements/docs.txt | 3 +++ 3 files changed, 5 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 5730680b173..d1efcd2494c 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/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 a3865b2e5f9..d42feab981d 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 From 1cc548a6f6c2fc7148189989a7b66fb4208ee8c8 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 17:17:34 +0200 Subject: [PATCH 10/31] Start managing use of example configuration files --- docs/user/config-file/examples/README | 12 ++++ .../examples/mkdocs/.readthedocs.yaml | 20 +++++++ .../examples/sphinx/.readthedocs.yaml | 32 +++++++++++ docs/user/config-file/v2.rst | 56 ++----------------- docs/user/guides/setup/configuration-file.rst | 31 ++++++++++ 5 files changed, 99 insertions(+), 52 deletions(-) create mode 100644 docs/user/config-file/examples/README create mode 100644 docs/user/config-file/examples/mkdocs/.readthedocs.yaml create mode 100644 docs/user/config-file/examples/sphinx/.readthedocs.yaml diff --git a/docs/user/config-file/examples/README b/docs/user/config-file/examples/README new file mode 100644 index 00000000000..d4e90363b32 --- /dev/null +++ b/docs/user/config-file/examples/README @@ -0,0 +1,12 @@ +README + +What is config-file/examples for? + +We are collecting all examples of configurations used in documentation and on +the website here. + +We are putting examples into subfolders and calling them `.readthedocs.yaml` +because each example might turn into a fully runnable example at some point. + +Examples should ultimately be possible to install as Read the Docs projects +using a custom configuration file path. 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..c56f9975493 --- /dev/null +++ b/docs/user/config-file/examples/mkdocs/.readthedocs.yaml @@ -0,0 +1,20 @@ +# .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 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..aa209bb218b --- /dev/null +++ b/docs/user/config-file/examples/sphinx/.readthedocs.yaml @@ -0,0 +1,32 @@ +# .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 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..1b14a4db8a7 100644 --- a/docs/user/config-file/v2.rst +++ b/docs/user/config-file/v2.rst @@ -12,62 +12,14 @@ 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 + :linenos: .. tab:: MkDocs - .. code:: yaml + .. literalinclude:: /config-file/examples/mkdocs/.readthedocs.yaml + :linenos: - # .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/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index 47617f6650c..c59effe08d2 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -37,6 +37,37 @@ Add a new file with the exact name ``.readthedocs.yaml`` in the repository's roo We will get to the contents of the file in a moment. +Examples to get started +----------------------- + +Here are some variations of the configuration file that can help you get started. +Pick the one that resembles your project the most. + +.. tabs:: + + .. tab:: Sphinx + + If your project uses Sphinx, + we offer a special builder optimized for Sphinx projects. + + .. literalinclude:: /config-file/examples/sphinx/.readthedocs.yaml + :linenos: + + + .. tab:: MkDocs + + If your project uses MkDocs, + we offer a special builder optimized for MkDocs projects. + + .. literalinclude:: /config-file/examples/mkdocs/.readthedocs.yaml + :linenos: + + .. tab:: Custom builder + + If you are using another tool, + you can configure the commands of your documentation tool in the following code. + + The required parts of your configuration file --------------------------------------------- From 69e4fb6c9435bcb8c44a575957af5bf5bcbe2cb4 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 22:11:47 +0200 Subject: [PATCH 11/31] Turn tip into seealso --- docs/user/guides/setup/configuration-file.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index c59effe08d2..174e5e67729 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -21,11 +21,11 @@ This how-to guide covers: This should be enough to get you started! -.. tip:: +.. seealso:: - The complete list of all possible ``.readthedocs.yaml`` settings, including - the optional settings not covered in on this page, is found on - :doc:`the configuration file reference page `. + :doc:`/config-file/index`. + The complete list of all possible ``.readthedocs.yaml`` settings, + including the optional settings not covered in on this page. Where to put your configuration file From 715fba5b316188545d4b43bfc6b4b1f8f0915ac5 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 22:58:59 +0200 Subject: [PATCH 12/31] Updates the how-to with more content editing, aligning more with a step-by-step guide --- .../custom-commands-echo/.readthedocs.yaml | 17 +++++ .../examples/mkdocs/.readthedocs.yaml | 2 +- .../examples/sphinx/.readthedocs.yaml | 2 +- docs/user/config-file/v2.rst | 4 +- docs/user/guides/setup/configuration-file.rst | 65 ++++++++++--------- 5 files changed, 58 insertions(+), 32 deletions(-) create mode 100644 docs/user/config-file/examples/custom-commands-echo/.readthedocs.yaml diff --git a/docs/user/config-file/examples/custom-commands-echo/.readthedocs.yaml b/docs/user/config-file/examples/custom-commands-echo/.readthedocs.yaml new file mode 100644 index 00000000000..140ee48ad24 --- /dev/null +++ b/docs/user/config-file/examples/custom-commands-echo/.readthedocs.yaml @@ -0,0 +1,17 @@ +# .readthedocs.yaml +# A bare Read the Docs configuration file for custom commands +# +# Introduction to custom build commands: +# https://docs.readthedocs.io/en/stable/build-customization.html +# +# Complete config file reference: +# https://docs.readthedocs.io/en/stable/config-file/v2.html +version: 2 + +build: + os: ubuntu-22.04 + commands: + # Create the directory that we should write html outputs to + - mkdir -p $READTHEDOCS_OUTPUT/html/ + # Write an index.html (it will be uploaded and published automatically) + - echo "Hola mundo!" > $READTHEDOCS_OUTPUT/html/index.html diff --git a/docs/user/config-file/examples/mkdocs/.readthedocs.yaml b/docs/user/config-file/examples/mkdocs/.readthedocs.yaml index c56f9975493..214b44fd68d 100644 --- a/docs/user/config-file/examples/mkdocs/.readthedocs.yaml +++ b/docs/user/config-file/examples/mkdocs/.readthedocs.yaml @@ -1,5 +1,5 @@ # .readthedocs.yaml -# Read the Docs configuration file +# Read the Docs configuration file for MkDocs setups # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details # Required diff --git a/docs/user/config-file/examples/sphinx/.readthedocs.yaml b/docs/user/config-file/examples/sphinx/.readthedocs.yaml index aa209bb218b..7a310077efb 100644 --- a/docs/user/config-file/examples/sphinx/.readthedocs.yaml +++ b/docs/user/config-file/examples/sphinx/.readthedocs.yaml @@ -1,5 +1,5 @@ # .readthedocs.yaml -# Read the Docs configuration file +# Read the Docs configuration file for Sphinx setups # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details # Required diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst index 1b14a4db8a7..5aaafddebe3 100644 --- a/docs/user/config-file/v2.rst +++ b/docs/user/config-file/v2.rst @@ -13,11 +13,13 @@ Below is an example YAML file which shows the most common configuration options: .. tab:: Sphinx .. literalinclude:: /config-file/examples/sphinx/.readthedocs.yaml - :linenos: + :language: yaml + :linenos: .. tab:: MkDocs .. literalinclude:: /config-file/examples/mkdocs/.readthedocs.yaml + :language: yaml :linenos: diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index 174e5e67729..a7f4c8e8547 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -37,8 +37,8 @@ Add a new file with the exact name ``.readthedocs.yaml`` in the repository's roo We will get to the contents of the file in a moment. -Examples to get started ------------------------ +Getting started with a template +------------------------------- Here are some variations of the configuration file that can help you get started. Pick the one that resembles your project the most. @@ -51,6 +51,7 @@ Pick the one that resembles your project the most. we offer a special builder optimized for Sphinx projects. .. literalinclude:: /config-file/examples/sphinx/.readthedocs.yaml + :language: yaml :linenos: @@ -60,16 +61,23 @@ Pick the one that resembles your project the most. we offer a special builder optimized for MkDocs projects. .. literalinclude:: /config-file/examples/mkdocs/.readthedocs.yaml + :language: yaml :linenos: - .. tab:: Custom builder + .. tab:: Other tools - If you are using another tool, + If you are using another documentation tool, you can configure the commands of your documentation tool in the following code. + You will need to create the output directories and direct your documentation tool to write its outputs into those directories. + + .. literalinclude:: /config-file/examples/custom-commands-echo/.readthedocs.yaml + :language: yaml + :linenos: -The required parts of your configuration file ---------------------------------------------- + +Editing the template +-------------------- The configuration file is a `YAML`_ file. YAML files are a "map": a collection of key-value pairs that can be nested. This is not unlike a JSON file or ``dict`` @@ -83,41 +91,40 @@ online. File header ~~~~~~~~~~~ -As a best practice, begin your file by providing the following. +The first part of the file does not need to be edited: -#. The name of the file -#. A quick explanation of what the file is -#. A link to +#. A comment explaning the configuration file. +#. A convenient comment with a link to :doc:`the configuration file reference page `. +#. The version key tells the system how to read the rest of the configuration +file. The current and only supported version is **version 2**. .. code-block:: yaml - :linenos: # .readthedocs.yaml - # Read the Docs configuration file - # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details - # <--Remove this comment and leave this line blank--> - - -Version of configuration file schema -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The version key tells the system how to read the rest of the configuration -file. The current and only supported version is **version 2**. - -.. code-block:: yaml - :linenos: - :lineno-start: 5 + # See the reference for the Read the Docs configuration file: + # https://docs.readthedocs.io/en/stable/config-file/v2.html for details version: 2 - # <--Remove this comment and leave this line blank--> Python requirements ~~~~~~~~~~~~~~~~~~~ -The ``python`` key contains several sub-keys, but only one sub-key is required: -``requirements``. However, since ``requirements`` is required, ``python`` is -too. +If you are using Python in your builds, +you should define the Python version. +You can also define your additional Python requirements. + +The ``python`` key contains a list of sub-keys, +specifying the requirements to install. 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. + +.. code-block:: yaml + + # 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 From 9145cfe7bbaf4a493b77368486ac91c0c2fea320 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 23:00:33 +0200 Subject: [PATCH 13/31] Fix a syntax err --- docs/user/guides/setup/configuration-file.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index a7f4c8e8547..bc1c9627f4b 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -96,8 +96,8 @@ The first part of the file does not need to be edited: #. A comment explaning the configuration file. #. A convenient comment with a link to :doc:`the configuration file reference page `. -#. The version key tells the system how to read the rest of the configuration -file. The current and only supported version is **version 2**. +#. The version key tells the system how to read the rest of the configuration file. + The current and only supported version is **version 2**. .. code-block:: yaml From 0c09e138008b072eb96be9a5aa4e25b5b6c4bf7c Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 23:03:57 +0200 Subject: [PATCH 14/31] Add some more fluffy text to bind the flow together --- docs/user/guides/setup/configuration-file.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index bc1c9627f4b..0d12d82d295 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -41,7 +41,8 @@ Getting started with a template ------------------------------- Here are some variations of the configuration file that can help you get started. -Pick the one that resembles your project the most. +Pick the one that resembles your project the most, +copy its contents to ``.readthedocs.yaml`` and add the file to your Git repository. .. tabs:: @@ -79,6 +80,11 @@ Pick the one that resembles your project the most. 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 file. + +But the file probably needs some changes to accomodate exactly your project setup. + The configuration file is a `YAML`_ file. YAML files are a "map": a collection of key-value pairs that can be nested. This is not unlike a JSON file or ``dict`` object in Python. From 9818ac1f456fa39ee6808c1266405fb8e86001a2 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 23:06:09 +0200 Subject: [PATCH 15/31] Remove redundant sentence --- docs/user/guides/setup/configuration-file.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index 0d12d82d295..148f45888fa 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -32,9 +32,7 @@ Where to put your configuration file ------------------------------------ The ``.readthedocs.yaml`` file should be placed in the top-most directory of your project's repository. - -Add a new file with the exact name ``.readthedocs.yaml`` in the repository's root directory. -We will get to the contents of the file in a moment. +We will get to the contents of the file in the next steps. Getting started with a template From fde407c719d08cc9cb9222408e99297bd0c048a4 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 23:24:31 +0200 Subject: [PATCH 16/31] Further refinements to the step-by-step structure --- docs/user/guides/setup/configuration-file.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index 148f45888fa..bc472e8f571 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -17,12 +17,14 @@ The configuration file tells the platform what specific settings to use for your This how-to guide covers: #. Where to put your configuration file. -#. What to add to your configuration file. - -This should be enough to get you started! +#. Templates to setup your configuration file from scratch. +#. The most basic sections in the configuration file that can help you get started. .. seealso:: + :doc:`/tutorial/index`. + Following the steps in our tutorial will help you setup your first documentation project. + :doc:`/config-file/index`. The complete list of all possible ``.readthedocs.yaml`` settings, including the optional settings not covered in on this page. @@ -34,6 +36,9 @@ 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 automatical find and use the configuration to build your project. Getting started with a template ------------------------------- @@ -79,7 +84,7 @@ 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 file. +you should see Read the Docs trying to build your project with the configuration file. But the file probably needs some changes to accomodate exactly your project setup. From 61a5322c4882360388e30235ef552f5e1b2a3fb7 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Jun 2023 23:28:00 +0200 Subject: [PATCH 17/31] Add Next Steps section --- docs/user/guides/setup/configuration-file.rst | 30 ++++++++++--------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index bc472e8f571..42d37706be8 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -3,32 +3,20 @@ How to add a configuration file As part of the initial setup for your Read the Docs site, you need to create a **configuration file** called ``.readthedocs.yaml``. - -The configuration file tells the platform what specific settings to use for your project. - -.. TODO: This isn't really how-to content. We might want to add "Configuration as Code" or similar to our features in order to deal with this. -.. I have another PR open where this is added. - -.. By using a configuration file, -.. you can tailor the behavior of Read the Docs to match your project's specific needs. -.. In addition that that, -.. using a configuration file can capture important configuration options that might otherwise break in the future if left undefined. +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. #. Templates to setup your configuration file from scratch. #. The most basic sections in the configuration file that can help you get started. +#. Next steps .. seealso:: :doc:`/tutorial/index`. Following the steps in our tutorial will help you setup your first documentation project. - :doc:`/config-file/index`. - The complete list of all possible ``.readthedocs.yaml`` settings, - including the optional settings not covered in on this page. - Where to put your configuration file ------------------------------------ @@ -137,3 +125,17 @@ that lists the Python packages you want Read the Docs to install. python: install: - requirements: docs/requirements.txt + +Next steps +---------- + +Once you have your configuration file added to 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. From 0907b6759110c6fc1c52abad730b1cd9ab32f0b0 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 8 Jun 2023 16:29:50 +0200 Subject: [PATCH 18/31] More step-by-step flow and copy editing --- docs/user/guides/setup/configuration-file.rst | 146 ++++++++++++++---- 1 file changed, 112 insertions(+), 34 deletions(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index 42d37706be8..3020fd22b58 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -10,7 +10,7 @@ This how-to guide covers: #. Where to put your configuration file. #. Templates to setup your configuration file from scratch. #. The most basic sections in the configuration file that can help you get started. -#. Next steps +#. Next steps... .. seealso:: @@ -26,7 +26,19 @@ 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 automatical find and use the configuration to build your project. +Read the Docs will then automatically find and use the configuration to build your project. + +.. note:: + + Why is it called .yaml? What is that? + The configuration file is a `YAML`_ file. YAML files are a "map": a collection of + key-value pairs that can be nested. This is not unlike a JSON file or ``dict`` + object in Python. This page won't explain the structure of YAML files, but many resources exist + online. + + +.. _YAML: https://en.wikipedia.org/wiki/YAML + Getting started with a template ------------------------------- @@ -73,67 +85,133 @@ 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. -But the file probably needs some changes to accomodate exactly your project setup. +.. note:: -The configuration file is a `YAML`_ file. YAML files are a "map": a collection of -key-value pairs that can be nested. This is not unlike a JSON file or ``dict`` -object in Python. + If you added the configuration file in a separate branch, + you may have to activate a :doc:`version ` for that branch. -This page won't explain the structure of YAML files, but many resources exist -online. + If you have added the file in a pull request, + you should enable :doc:`pull request builds `. -.. _YAML: https://en.wikipedia.org/wiki/YAML +Skip: file header and comments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are some parts of the templates that you can leave in place: -File header -~~~~~~~~~~~ +Comments + We added a lot of comments that explain stuff. They begin with a ``#``. -The first part of the file does not need to be edited: +Commented out features + Similar to comments, we also use the ``#`` in front of some configuration options that may or may not be relevant. + To enable something that's commented out, + simply delete the ``#`` and a blank space in front of the YAML code that you want to enable. -#. A comment explaning the configuration file. -#. A convenient comment with a link to - :doc:`the configuration file reference page `. -#. The version key tells the system how to read the rest of the configuration file. - The current and only supported version is **version 2**. +``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**. -.. code-block:: yaml - # .readthedocs.yaml - # See the reference for the Read the Docs configuration file: - # https://docs.readthedocs.io/en/stable/config-file/v2.html for details +Adjust: ``build.os`` +~~~~~~~~~~~~~~~~~~~~ - version: 2 +In our examples, +we are using Read the Docs' custom image based on the latest Ubuntu LTS release. +LTS means long-term support, +meaning that your builds should not break within next many years. -Python requirements -~~~~~~~~~~~~~~~~~~~ +However, +you should pay attention to this field if your current 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. -You can also define your additional Python requirements. +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. -.. code-block:: yaml +.. 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. + +.. _config_howto_build.tools: + +Adjust: Additional build environments? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need software from additional platforms (nodejs, rust, golang), +you can add and enable such an environment so you can install the packages you need. + +.. seealso:: + + :ref:`config-file/v2:build.tools` + List of all tools that are possible to enable. + +Adjust: Custom tools +~~~~~~~~~~~~~~~~~~~~ + +It's possible to build documentation using almost any documentation tool, +as long as an environment is available (see :ref:`the previous step `). + +.. seealso:: + + :doc:`/build-customization` + Jump to a full guide explaining how to setup (almost) any documentation tool. + + :ref:`config-file/v2:build.commands` + Configuration file reference for custom build commands. - # 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 Next steps ---------- +The configuration options that we mentioned in this guide aren't all. +There are more. + Once you have your configuration file added to 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`. From 0d51abbb47a4adba86258f05a1d67283c4ce7e4e Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 8 Jun 2023 16:30:15 +0200 Subject: [PATCH 19/31] Adds a tip (inspired by possible Configuration File howto UX) --- docs/user/guides/pull-requests.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/user/guides/pull-requests.rst b/docs/user/guides/pull-requests.rst index c4c001602e3..827eb57855f 100644 --- a/docs/user/guides/pull-requests.rst +++ b/docs/user/guides/pull-requests.rst @@ -14,6 +14,12 @@ If your account is already connected: #. Enable the :guilabel:`Build pull requests for this project` option #. Click on :guilabel:`Save` +.. tip:: + + Pull requests that existed before enabling pull request builds will not be detected immediately. + But once you push a new commit to an existing pull request, + it will start building. + Privacy levels -------------- From 4098d85a128e12acd62464f2934b9b0cccaca86d Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 8 Jun 2023 16:43:14 +0200 Subject: [PATCH 20/31] More content for build.commands --- docs/user/guides/setup/configuration-file.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index 3020fd22b58..639a1ac8138 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -39,6 +39,7 @@ Read the Docs will then automatically find and use the configuration to build yo .. _YAML: https://en.wikipedia.org/wiki/YAML +.. _howto_templates: Getting started with a template ------------------------------- @@ -192,6 +193,9 @@ Adjust: Custom tools It's possible to build documentation using almost any documentation tool, as long as an environment is available (see :ref:`the previous step `). +Adding your own build commands is done by listing them in ``build.commands``. + +The :ref:`Other tools ` template shows an example of how to do that. .. seealso:: From 4eb0ba39e379a8bea136a3382bea47f83a46b522 Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Fri, 9 Jun 2023 11:28:07 +0200 Subject: [PATCH 21/31] Apply suggestions from @agjohnson code review with some additional suggestions from @benjaoming Co-authored-by: Anthony --- docs/user/config-file/examples/README | 6 ---- .../examples/mkdocs/.readthedocs.yaml | 2 +- .../examples/sphinx/.readthedocs.yaml | 3 +- docs/user/config-file/v2.rst | 2 ++ docs/user/guides/pull-requests.rst | 5 ++- docs/user/guides/setup/configuration-file.rst | 34 ++++++++++--------- docs/user/guides/setup/index.rst | 2 +- 7 files changed, 25 insertions(+), 29 deletions(-) diff --git a/docs/user/config-file/examples/README b/docs/user/config-file/examples/README index d4e90363b32..1c6b89b63ef 100644 --- a/docs/user/config-file/examples/README +++ b/docs/user/config-file/examples/README @@ -4,9 +4,3 @@ What is config-file/examples for? We are collecting all examples of configurations used in documentation and on the website here. - -We are putting examples into subfolders and calling them `.readthedocs.yaml` -because each example might turn into a fully runnable example at some point. - -Examples should ultimately be possible to install as Read the Docs projects -using a custom configuration file path. diff --git a/docs/user/config-file/examples/mkdocs/.readthedocs.yaml b/docs/user/config-file/examples/mkdocs/.readthedocs.yaml index 214b44fd68d..a6779b0b116 100644 --- a/docs/user/config-file/examples/mkdocs/.readthedocs.yaml +++ b/docs/user/config-file/examples/mkdocs/.readthedocs.yaml @@ -1,5 +1,5 @@ # .readthedocs.yaml -# Read the Docs configuration file for MkDocs setups +# Read the Docs configuration file for MkDocs projects # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details # Required diff --git a/docs/user/config-file/examples/sphinx/.readthedocs.yaml b/docs/user/config-file/examples/sphinx/.readthedocs.yaml index 7a310077efb..4484bf0e72b 100644 --- a/docs/user/config-file/examples/sphinx/.readthedocs.yaml +++ b/docs/user/config-file/examples/sphinx/.readthedocs.yaml @@ -1,5 +1,4 @@ -# .readthedocs.yaml -# Read the Docs configuration file for Sphinx setups +# Read the Docs configuration file for Sphinx projects # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details # Required diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst index 5aaafddebe3..77d6ae0d5f4 100644 --- a/docs/user/config-file/v2.rst +++ b/docs/user/config-file/v2.rst @@ -15,12 +15,14 @@ Below is an example YAML file which shows the most common configuration options: .. literalinclude:: /config-file/examples/sphinx/.readthedocs.yaml :language: yaml :linenos: + :caption: .readthedocs.yaml .. tab:: MkDocs .. literalinclude:: /config-file/examples/mkdocs/.readthedocs.yaml :language: yaml :linenos: + :caption: .readthedocs.yaml Supported settings diff --git a/docs/user/guides/pull-requests.rst b/docs/user/guides/pull-requests.rst index 827eb57855f..386cc13f6a2 100644 --- a/docs/user/guides/pull-requests.rst +++ b/docs/user/guides/pull-requests.rst @@ -16,9 +16,8 @@ If your account is already connected: .. tip:: - Pull requests that existed before enabling pull request builds will not be detected immediately. - But once you push a new commit to an existing pull request, - it will start building. + 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 index 639a1ac8138..948c9d45ea6 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -1,16 +1,15 @@ How to add a configuration file =============================== -As part of the initial setup for your Read the Docs site, +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. -#. Templates to setup your configuration file from scratch. -#. The most basic sections in the configuration file that can help you get started. -#. Next steps... +#. What to put in the configuration file. +#. How to customize the configuration for your project. .. seealso:: @@ -44,8 +43,8 @@ Read the Docs will then automatically find and use the configuration to build yo Getting started with a template ------------------------------- -Here are some variations of the configuration file that can help you get started. -Pick the one that resembles your project the most, +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:: @@ -58,6 +57,7 @@ copy its contents to ``.readthedocs.yaml`` and add the file to your Git reposito .. literalinclude:: /config-file/examples/sphinx/.readthedocs.yaml :language: yaml :linenos: + :caption: .readthedocs.yaml .. tab:: MkDocs @@ -68,6 +68,7 @@ copy its contents to ``.readthedocs.yaml`` and add the file to your Git reposito .. literalinclude:: /config-file/examples/mkdocs/.readthedocs.yaml :language: yaml :linenos: + :caption: .readthedocs.yaml .. tab:: Other tools @@ -102,12 +103,13 @@ Skip: file header and comments There are some parts of the templates that you can leave in place: Comments - We added a lot of comments that explain stuff. They begin with a ``#``. + We added comments that explain the configuration options and optional features. + These lines begin with a ``#``. Commented out features - Similar to comments, we also use the ``#`` in front of some configuration options that may or may not be relevant. - To enable something that's commented out, - simply delete the ``#`` and a blank space in front of the YAML code that you want to enable. + 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. @@ -123,7 +125,7 @@ LTS means long-term support, meaning that your builds should not break within next many years. However, -you should pay attention to this field if your current project needs to build on an older version of Ubuntu, +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:: @@ -177,11 +179,11 @@ that lists the Python packages you want Read the Docs to install. .. _config_howto_build.tools: -Adjust: Additional build environments? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Adjust: Additional build tools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you need software from additional platforms (nodejs, rust, golang), -you can add and enable such an environment so you can install the packages you need. +If you need additional build tools (Node.js, Rust, Go), +you can define the versions of these tools to install as well, using the ``build.tools`` key. .. seealso:: @@ -212,7 +214,7 @@ Next steps The configuration options that we mentioned in this guide aren't all. There are more. -Once you have your configuration file added to your Git repository, +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. diff --git a/docs/user/guides/setup/index.rst b/docs/user/guides/setup/index.rst index 703dbf19974..228231bee9d 100644 --- a/docs/user/guides/setup/index.rst +++ b/docs/user/guides/setup/index.rst @@ -15,7 +15,7 @@ The following how-to guides help you solve common tasks and challenges in the se this guide tells you how to add and configure the webhook **manually**. ⏊ :doc:`Adding a configuration file ` - When setting up a new project, + To build your documentation project, you need to add a ``.readthedocs.yaml`` configuration file. This guide gets you started. From 811f11825acb7eafba8b59f01e9ec990d2b0eb29 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 9 Jun 2023 11:30:48 +0200 Subject: [PATCH 22/31] Trim the weird .readthedocs.yaml comment --- .../config-file/examples/custom-commands-echo/.readthedocs.yaml | 1 - docs/user/config-file/examples/mkdocs/.readthedocs.yaml | 1 - 2 files changed, 2 deletions(-) diff --git a/docs/user/config-file/examples/custom-commands-echo/.readthedocs.yaml b/docs/user/config-file/examples/custom-commands-echo/.readthedocs.yaml index 140ee48ad24..a7076adf77b 100644 --- a/docs/user/config-file/examples/custom-commands-echo/.readthedocs.yaml +++ b/docs/user/config-file/examples/custom-commands-echo/.readthedocs.yaml @@ -1,4 +1,3 @@ -# .readthedocs.yaml # A bare Read the Docs configuration file for custom commands # # Introduction to custom build commands: diff --git a/docs/user/config-file/examples/mkdocs/.readthedocs.yaml b/docs/user/config-file/examples/mkdocs/.readthedocs.yaml index a6779b0b116..c5587fb24a4 100644 --- a/docs/user/config-file/examples/mkdocs/.readthedocs.yaml +++ b/docs/user/config-file/examples/mkdocs/.readthedocs.yaml @@ -1,4 +1,3 @@ -# .readthedocs.yaml # Read the Docs configuration file for MkDocs projects # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details From 166549b5b57de53e64177e9caeed70df426ad817 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 9 Jun 2023 14:29:50 +0200 Subject: [PATCH 23/31] Refactor: Remove the "bare" echo example and use Docusaurus instead. Remove section about custom commands and instead have it hidden in a tab --- docs/user/build-customization.rst | 2 + docs/user/config-file/examples/README | 6 +- .../custom-commands-echo/.readthedocs.yaml | 16 ----- .../examples/docusaurus/.readthedocs.yaml | 28 +++++++++ docs/user/guides/setup/configuration-file.rst | 62 +++++++++++-------- 5 files changed, 69 insertions(+), 45 deletions(-) delete mode 100644 docs/user/config-file/examples/custom-commands-echo/.readthedocs.yaml create mode 100644 docs/user/config-file/examples/docusaurus/.readthedocs.yaml 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 index 1c6b89b63ef..606d8da8b3d 100644 --- a/docs/user/config-file/examples/README +++ b/docs/user/config-file/examples/README @@ -2,5 +2,7 @@ README What is config-file/examples for? -We are collecting all examples of configurations used in documentation and on -the website here. +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/custom-commands-echo/.readthedocs.yaml b/docs/user/config-file/examples/custom-commands-echo/.readthedocs.yaml deleted file mode 100644 index a7076adf77b..00000000000 --- a/docs/user/config-file/examples/custom-commands-echo/.readthedocs.yaml +++ /dev/null @@ -1,16 +0,0 @@ -# A bare Read the Docs configuration file for custom commands -# -# Introduction to custom build commands: -# https://docs.readthedocs.io/en/stable/build-customization.html -# -# Complete config file reference: -# https://docs.readthedocs.io/en/stable/config-file/v2.html -version: 2 - -build: - os: ubuntu-22.04 - commands: - # Create the directory that we should write html outputs to - - mkdir -p $READTHEDOCS_OUTPUT/html/ - # Write an index.html (it will be uploaded and published automatically) - - echo "Hola mundo!" > $READTHEDOCS_OUTPUT/html/index.html diff --git a/docs/user/config-file/examples/docusaurus/.readthedocs.yaml b/docs/user/config-file/examples/docusaurus/.readthedocs.yaml new file mode 100644 index 00000000000..d128e151d22 --- /dev/null +++ b/docs/user/config-file/examples/docusaurus/.readthedocs.yaml @@ -0,0 +1,28 @@ +# Custom build commands to build and publish a docusaurus project +# +# To bootstrap an example documentation project in docs/ for this template, +# you can use the following npx command: +# +# npx create-docusaurus@latest docs classic +# +# Introduction to custom build commands: +# https://docs.readthedocs.io/en/stable/build-customization.html +# +# Complete config file reference: +# https://docs.readthedocs.io/en/stable/config-file/v2.html +version: 2 + +build: + os: ubuntu-22.04 + tools: + nodejs: "18" + + # We assume that a docusaurus project exists in docs/ + commands: + # Install Docusaurus and its dependencies + - cd docs/ && npm install + # Build the site + - cd docs/ && npm run build + # Copy generated files into Read the Docs output directory + - mkdir --parents $READTHEDOCS_OUTPUT/html/ + - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/ diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index 948c9d45ea6..e61284c3392 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -70,17 +70,27 @@ copy its contents to ``.readthedocs.yaml`` and add the file to your Git reposito :linenos: :caption: .readthedocs.yaml - .. tab:: Other tools + .. tab:: Docusaurus - If you are using another documentation tool, - you can configure the commands of your documentation tool in the following code. + If you are using `Docusaurus `__, + we provide support through the following template. - You will need to create the output directories and direct your documentation tool to write its outputs into those directories. + Each step is explained in the comments and elaborated in this how-to. .. literalinclude:: /config-file/examples/custom-commands-echo/.readthedocs.yaml :language: yaml :linenos: + .. tab:: Other tools + + Using another documentation tool than the ones shown here? + + You can overwrite the commands of your documentation tool in a similar fashion shown in the Docusaurus template. + We recommend looking at :ref:`build-customization:build_commands_introduction` for a more complete introduction to setting up a custom documentation tool. + + Meanwhile, we are brewing together templates for additional documentation tools, + and we very much welcome you to proposals in `our GitHub issue tracker `__ 🍰ī¸ + Editing the template -------------------- @@ -177,42 +187,35 @@ that lists the Python packages you want Read the Docs to install. :ref:`config-file/v2:mkdocs` Configuration file reference for configuring the MkDocs builder. -.. _config_howto_build.tools: +Adjust: Docusaurus +~~~~~~~~~~~~~~~~~~ -Adjust: Additional build tools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The template for :ref:`Docusaurus ` shows a slightly more complex example of using a custom documentation tool. -If you need additional build tools (Node.js, Rust, Go), -you can define the versions of these tools to install as well, using the ``build.tools`` key. +What's needed are the following steps: -.. seealso:: +1. Install the custom documentation tool in its environment. + To build a Docusaurus project, + we need to enable a Node.js environment and then we install docusarus. - :ref:`config-file/v2:build.tools` - List of all tools that are possible to enable. +2. Run the documentation tool! -Adjust: Custom tools -~~~~~~~~~~~~~~~~~~~~ - -It's possible to build documentation using almost any documentation tool, -as long as an environment is available (see :ref:`the previous step `). -Adding your own build commands is done by listing them in ``build.commands``. +3. Move the outputs into their expected location. + Here, we use the pre-defined ``$READTHEDOCS_OUTPUT`` :doc:`environment variable `. -The :ref:`Other tools ` template shows an example of how to do that. +Notice in the template that ``docs/`` is used as the path for your Docusaurus project. +If it's stored in another location, +you should adjust this. .. seealso:: - :doc:`/build-customization` - Jump to a full guide explaining how to setup (almost) any documentation tool. - - :ref:`config-file/v2:build.commands` - Configuration file reference for custom build commands. - + :ref:`build-customization:build_commands_introduction` + Read more about how to add your own commands in the build process. Next steps ---------- -The configuration options that we mentioned in this guide aren't all. -There are more. +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, @@ -223,3 +226,8 @@ you should have a look at the complete configuration file reference for options :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``. From 8501d883cbe79e5020532e62fa943f72b53caaeb Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 9 Jun 2023 14:34:44 +0200 Subject: [PATCH 24/31] Fix some references --- docs/user/guides/setup/configuration-file.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index e61284c3392..d9c43ffba14 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -77,7 +77,7 @@ copy its contents to ``.readthedocs.yaml`` and add the file to your Git reposito Each step is explained in the comments and elaborated in this how-to. - .. literalinclude:: /config-file/examples/custom-commands-echo/.readthedocs.yaml + .. literalinclude:: /config-file/examples/docusaurus/.readthedocs.yaml :language: yaml :linenos: @@ -86,7 +86,7 @@ copy its contents to ``.readthedocs.yaml`` and add the file to your Git reposito Using another documentation tool than the ones shown here? You can overwrite the commands of your documentation tool in a similar fashion shown in the Docusaurus template. - We recommend looking at :ref:`build-customization:build_commands_introduction` for a more complete introduction to setting up a custom documentation tool. + We recommend looking at :ref:`build_commands_introduction` for a more complete introduction to setting up a custom documentation tool. Meanwhile, we are brewing together templates for additional documentation tools, and we very much welcome you to proposals in `our GitHub issue tracker `__ 🍰ī¸ @@ -209,7 +209,7 @@ you should adjust this. .. seealso:: - :ref:`build-customization:build_commands_introduction` + :ref:`build_commands_introduction` Read more about how to add your own commands in the build process. Next steps From a2de19bb854f6836d9661b69e6d23319515aa504 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 9 Jun 2023 20:58:19 +0200 Subject: [PATCH 25/31] Fix a crashed sentence --- docs/user/guides/setup/configuration-file.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index d9c43ffba14..f955a9de3d2 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -89,7 +89,7 @@ copy its contents to ``.readthedocs.yaml`` and add the file to your Git reposito We recommend looking at :ref:`build_commands_introduction` for a more complete introduction to setting up a custom documentation tool. Meanwhile, we are brewing together templates for additional documentation tools, - and we very much welcome you to proposals in `our GitHub issue tracker `__ 🍰ī¸ + and we welcome your proposal in `our GitHub issue tracker `__ 🍰ī¸ Editing the template From 92b1fc929a1f77d1c7ebb7395361d884219c100f Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 9 Jun 2023 21:01:40 +0200 Subject: [PATCH 26/31] Eliminate seealso from Docusaurus section (an almost identical one is in Next Steps) --- docs/user/guides/setup/configuration-file.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index f955a9de3d2..ff8f5041ed1 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -207,11 +207,6 @@ Notice in the template that ``docs/`` is used as the path for your Docusaurus pr If it's stored in another location, you should adjust this. -.. seealso:: - - :ref:`build_commands_introduction` - Read more about how to add your own commands in the build process. - Next steps ---------- From 7c3632c0c86ca2ad3ec7a62e1ac2f7975b99fcb2 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 9 Jun 2023 22:06:40 +0200 Subject: [PATCH 27/31] Remove Docusaurus template --- .../examples/docusaurus/.readthedocs.yaml | 28 ------------------- docs/user/guides/setup/configuration-file.rst | 22 --------------- 2 files changed, 50 deletions(-) delete mode 100644 docs/user/config-file/examples/docusaurus/.readthedocs.yaml diff --git a/docs/user/config-file/examples/docusaurus/.readthedocs.yaml b/docs/user/config-file/examples/docusaurus/.readthedocs.yaml deleted file mode 100644 index d128e151d22..00000000000 --- a/docs/user/config-file/examples/docusaurus/.readthedocs.yaml +++ /dev/null @@ -1,28 +0,0 @@ -# Custom build commands to build and publish a docusaurus project -# -# To bootstrap an example documentation project in docs/ for this template, -# you can use the following npx command: -# -# npx create-docusaurus@latest docs classic -# -# Introduction to custom build commands: -# https://docs.readthedocs.io/en/stable/build-customization.html -# -# Complete config file reference: -# https://docs.readthedocs.io/en/stable/config-file/v2.html -version: 2 - -build: - os: ubuntu-22.04 - tools: - nodejs: "18" - - # We assume that a docusaurus project exists in docs/ - commands: - # Install Docusaurus and its dependencies - - cd docs/ && npm install - # Build the site - - cd docs/ && npm run build - # Copy generated files into Read the Docs output directory - - mkdir --parents $READTHEDOCS_OUTPUT/html/ - - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/ diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index ff8f5041ed1..7490e1fe81a 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -70,28 +70,6 @@ copy its contents to ``.readthedocs.yaml`` and add the file to your Git reposito :linenos: :caption: .readthedocs.yaml - .. tab:: Docusaurus - - If you are using `Docusaurus `__, - we provide support through the following template. - - Each step is explained in the comments and elaborated in this how-to. - - .. literalinclude:: /config-file/examples/docusaurus/.readthedocs.yaml - :language: yaml - :linenos: - - .. tab:: Other tools - - Using another documentation tool than the ones shown here? - - You can overwrite the commands of your documentation tool in a similar fashion shown in the Docusaurus template. - We recommend looking at :ref:`build_commands_introduction` for a more complete introduction to setting up a custom documentation tool. - - Meanwhile, we are brewing together templates for additional documentation tools, - and we welcome your proposal in `our GitHub issue tracker `__ 🍰ī¸ - - Editing the template -------------------- From 2aecfbd09260f2ee3d0b9f8c3c38c362c0334f30 Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Fri, 9 Jun 2023 13:12:39 -0700 Subject: [PATCH 28/31] Remove section on adjusting for Docusaurus support --- docs/user/guides/setup/configuration-file.rst | 20 ------------------- 1 file changed, 20 deletions(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index 7490e1fe81a..f50dc757112 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -165,26 +165,6 @@ that lists the Python packages you want Read the Docs to install. :ref:`config-file/v2:mkdocs` Configuration file reference for configuring the MkDocs builder. -Adjust: Docusaurus -~~~~~~~~~~~~~~~~~~ - -The template for :ref:`Docusaurus ` shows a slightly more complex example of using a custom documentation tool. - -What's needed are the following steps: - -1. Install the custom documentation tool in its environment. - To build a Docusaurus project, - we need to enable a Node.js environment and then we install docusarus. - -2. Run the documentation tool! - -3. Move the outputs into their expected location. - Here, we use the pre-defined ``$READTHEDOCS_OUTPUT`` :doc:`environment variable `. - -Notice in the template that ``docs/`` is used as the path for your Docusaurus project. -If it's stored in another location, -you should adjust this. - Next steps ---------- From 46fa1aff916c128b2c20b0f62f09cacd0eb8eedc Mon Sep 17 00:00:00 2001 From: Anthony Date: Fri, 9 Jun 2023 13:15:36 -0700 Subject: [PATCH 29/31] Point to the YAML site and simplify copy on our YAML note --- docs/user/guides/setup/configuration-file.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index f50dc757112..654417843a3 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -29,14 +29,12 @@ Read the Docs will then automatically find and use the configuration to build yo .. note:: - Why is it called .yaml? What is that? - The configuration file is a `YAML`_ file. YAML files are a "map": a collection of - key-value pairs that can be nested. This is not unlike a JSON file or ``dict`` - object in Python. This page won't explain the structure of YAML files, but many resources exist - online. - - -.. _YAML: https://en.wikipedia.org/wiki/YAML + 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: From 18b209f75e58b423caa0a13c736e80e3d0365c8c Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Fri, 9 Jun 2023 13:32:38 -0700 Subject: [PATCH 30/31] Change note on Ubuntu image and package versions --- docs/user/guides/setup/configuration-file.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index 654417843a3..f3e98636044 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -106,12 +106,11 @@ Adjust: ``build.os`` ~~~~~~~~~~~~~~~~~~~~ In our examples, -we are using Read the Docs' custom image based on the latest Ubuntu LTS release. -LTS means long-term support, -meaning that your builds should not break within next many years. +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. -However, -you should pay attention to this field if your project needs to build on an older version of Ubuntu, +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:: From 01db9773139086c6c65150be909577501b5c34dd Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Fri, 9 Jun 2023 13:34:27 -0700 Subject: [PATCH 31/31] Doc lint --- docs/user/guides/setup/configuration-file.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/guides/setup/configuration-file.rst b/docs/user/guides/setup/configuration-file.rst index f3e98636044..035cc3cb29c 100644 --- a/docs/user/guides/setup/configuration-file.rst +++ b/docs/user/guides/setup/configuration-file.rst @@ -32,7 +32,7 @@ Read the Docs will then automatically find and use the configuration to build yo 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