Skip to content

Promote the YAML config #5485

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 18, 2019
Merged

Promote the YAML config #5485

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 30 additions & 15 deletions docs/config-file/v2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,40 @@ Configuration File V2
Read the Docs supports configuring your documentation builds with a YAML file.
:doc:`The Read the Docs file <index>` must be in the root directory of your project.

Here is an example of how this file looks like:
Below is an example YAML file which may require some changes for your project's configuration:

.. code:: yaml

# .readthedocs.yml
# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

version: 2
# Required
version: 2

# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py

# Build documentation with MkDocs
#mkdocs:
# configuration: mkdocs.yml

# Optionally build your docs in additional formats such as PDF and ePub
formats: all

# Optionally set the version of Python and requirements required to build your docs
python:
version: 3.7
install:
- requirements: docs/requirements.txt

python:
version: 3.7
install:
- method: pip
path: .

Supported settings
------------------

.. note::

The presence of any other key that isn't documented here will make the build to fail.
This is to avoid typos and provide feedback on invalid configurations.

Expand All @@ -34,11 +49,11 @@ version
Example:

.. code-block:: yaml

version: 2

.. warning::

If you don't provide the version, :doc:`v1 <v1>` will be used.

formats
Expand Down Expand Up @@ -329,13 +344,13 @@ VCS submodules configuration.
Only Git is supported at the moment.

.. note::

You can't use ``include`` and ``exclude`` settings for submodules at the same time.

Example:

.. code-block:: yaml

submodules:
include:
- one
Expand All @@ -351,7 +366,7 @@ List of submodules to be included.
:Default: ``[]``

.. note::

You can use the ``all`` keyword to include all submodules.

.. code-block:: yaml
Expand All @@ -368,7 +383,7 @@ List of submodules to be excluded.
:Default: ``[]``

.. note::

You can use the ``all`` keyword to exclude all submodules.
This is the same as ``include: []``.

Expand Down
7 changes: 3 additions & 4 deletions readthedocs/templates/projects/import_basics.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,9 @@ <h3>{% trans "Project Details" %}</h3>

<p class="info">
{% blocktrans trimmed %}
To import a project,
start by entering a few details about your repository.
More advanced project options can be configured
if you select <b>Edit advanced project options</b>.
To import a project, start by entering a few details about your repository.
You can set additional configuration options for your documentation in a
<a href="https://docs.readthedocs.io/en/stable/config-file/v2.html">.readthedocs.yml</a> file.
{% endblocktrans %}
</p>

Expand Down