From e773701f9fd9a685bfacb9affcd5c229e6eeaba5 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 16 Feb 2021 11:04:43 -0500 Subject: [PATCH] Use only one variant of the config file Why `.readthedocs.yaml`? - Configuration files usually start with a `.` so they are hidden in unix like systems. - `.yaml` is the official and recommended extension for yaml files. We could go a little further and use a feature flag to stop finding the other ones. ref https://github.com/readthedocs/readthedocs.org/issues/7915 --- docs/config-file/index.rst | 10 +++++----- docs/config-file/v1.rst | 2 +- docs/config-file/v2.rst | 8 ++++---- docs/intro/import-guide.rst | 2 +- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/config-file/index.rst b/docs/config-file/index.rst index 554738980c4..37004cc887a 100644 --- a/docs/config-file/index.rst +++ b/docs/config-file/index.rst @@ -3,12 +3,12 @@ Configuration File In addition to using the admin panel of your project to configure your project, you can use a configuration file in the root of your project. -The configuration file can be named: +The configuration file should be named ``.readthedocs.yaml``. -- ``readthedocs.yml`` -- ``readthedocs.yaml`` -- ``.readthedocs.yml`` -- ``.readthedocs.yaml`` +.. note:: + + Some other variants like ``readthedocs.yaml``, ``.readthedocs.yml``, etc + are deprecated. The main advantages of using a configuration file over the web interface are: diff --git a/docs/config-file/v1.rst b/docs/config-file/v1.rst index ce095fca9d1..3506327f8db 100644 --- a/docs/config-file/v1.rst +++ b/docs/config-file/v1.rst @@ -15,7 +15,7 @@ Here is an example of what this file looks like: .. code:: yaml - # .readthedocs.yml + # .readthedocs.yaml build: image: latest diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 15501e6ae93..d0e9a5ba6b1 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -2,8 +2,8 @@ Configuration File V2 ===================== Read the Docs supports configuring your documentation builds with a YAML file. -The :doc:`configuration file ` must be in the root directory of your project. -We recommend the filename ``.readthedocs.yml``. +The :doc:`configuration file ` must be in the root directory of your project +an be named ``.readthedocs.yaml``. All options are applied to the version containing this file. Below is an example YAML file which shows the most common configuration options: @@ -14,7 +14,7 @@ Below is an example YAML file which shows the most common configuration options: .. code:: yaml - # .readthedocs.yml + # .readthedocs.yaml # Read the Docs configuration file # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details @@ -39,7 +39,7 @@ Below is an example YAML file which shows the most common configuration options: .. code:: yaml - # .readthedocs.yml + # .readthedocs.yaml # Read the Docs configuration file # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details diff --git a/docs/intro/import-guide.rst b/docs/intro/import-guide.rst index 7da0f7e0121..9cbd244e485 100644 --- a/docs/intro/import-guide.rst +++ b/docs/intro/import-guide.rst @@ -72,7 +72,7 @@ and to troubleshoot any issues that arise. Some documentation projects require additional configuration to build such as specifying a certain version of Python or installing additional dependencies. -You can configure these settings in a ``readthedocs.yml`` file. +You can configure these settings in a ``.readthedocs.yaml`` file. See our :doc:`/config-file/index` docs for more details. It is also important to note that the default version of Sphinx is ``v1.8.5``.