Skip to content

Commit f261ecc

Browse files
stsewdstsewd
committed
Merge branch 'main' into build-api-token-access
2 parents 475fee7 + 187e698 commit f261ecc

File tree

15 files changed

+282
-61
lines changed

15 files changed

+282
-61
lines changed

‎docs/user/abandoned-projects.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,31 @@ following are met:
8383
* The project has fewer than 100 monthly pageviews
8484
* The core team does not have any additional reservations.
8585

86+
87+
Reporting an abandoned project
88+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
89+
90+
You can report an abandoned project according to this policy by contacting our :doc:`/support`.
91+
92+
Please include the following information:
93+
94+
.. code-block:: text
95+
96+
URL of abandoned documentation project: ...
97+
URL of abandoned project's repository (if any): ...
98+
URL of abandoned project's website (if any): ...
99+
100+
Are you suggesting that an alternative project should take over the
101+
name (slug) abandoned project? (y/n)
102+
103+
URL of alternative documentation (if any): ...
104+
URL of alternative website (if any): ...
105+
URL of alternative repository (if any): ...
106+
107+
Describe attempts of reaching the owner(s) of the abandoned project:
108+
...
109+
110+
86111
Name conflict resolution for active projects
87112
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
88113

‎docs/user/config-file/index.rst

Lines changed: 107 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,120 @@
1-
Configuration file
2-
==================
1+
Using a configuration file
2+
==========================
33

4-
In addition to using the admin panel of your project to configure your project,
5-
you can use a configuration file in the root of your project.
6-
The configuration file should be named ``.readthedocs.yaml``.
4+
Content and structure of documentation undergo big and small changes.
5+
And eventually, the configuration of a documentation project also changes.
6+
This means you need to be able to track these changes over time,
7+
and keep them up to date.
78

8-
.. note::
9+
In this article,
10+
we cover the major concepts of using a configuration file:
911

10-
Some other variants like ``readthedocs.yaml``, ``.readthedocs.yml``, etc
11-
are deprecated.
12+
Versioning the configuration
13+
A documentation project and its configuration file live together in a Git repository
14+
and are versioned together.
15+
16+
Configuration as code
17+
Configuration uses the same workflow as your source code,
18+
including being reviewed and tested in a Pull Request.
19+
20+
Options that are not found in the configuration file
21+
Not everything is suitable for version-specific configuration,
22+
like the Git repository where the configuration file is read after cloning.
23+
24+
.. seealso::
25+
26+
:doc:`/guides/setup/configuration-file`
27+
Practical steps to add a configuration file to your documentation project.
28+
29+
:doc:`/config-file/v2`
30+
Reference for configuration file settings.
31+
32+
33+
Why version your project's configuration?
34+
-----------------------------------------
35+
36+
Consider the following aspects of a documentation project:
37+
38+
Build environments change 📦️
39+
You may depend on a number of packages but your method for installing them changes.
40+
What is installed, how it's installed and what installs can change,
41+
especially across multiple versions.
42+
43+
You might change between Pip and Poetry.
44+
You might also jump between Python 2 and 3 or Python 3.8 and Python 3.10.
45+
46+
Documentation tools change ⚙️
47+
Using Sphinx? Using MkDocs? Or some other tool?
48+
All these tools have their own configuration files and special ways to invoke them.
49+
In order to switch between how you are invoking the tool and setting up its environment,
50+
you will need external build configuration.
51+
52+
Comparing changes over time ⚖️
53+
As your project changes, you will need to change your configuration.
54+
You might wonder how something was done in the past,
55+
and having it versioned means you can see each commit as it has changed.
56+
57+
You can configure your Read the Docs project by adding a ``.readthedocs.yaml`` file [1]_ to your Git repository.
58+
The configuration will apply to the exact version that is being built.
59+
This allows you to store different configurations for different versions of your documentation.
1260

1361
The main advantages of using a configuration file over the web interface are:
1462

1563
- Settings are per version rather than per project.
16-
- Settings live in your VCS.
64+
- Settings live in your Git repository.
1765
- They enable reproducible build environments over time.
1866
- Some settings are only available using a configuration file
1967

20-
.. tip::
68+
.. [1] Other variants of the configuration file name like ``readthedocs.yaml``, ``.readthedocs.yml``, etc. are deprecated.
69+
You may however, :doc:`configure a custom sub-folder </guides/setup/monorepo>`.
70+
71+
Configuration as Code
72+
---------------------
73+
74+
"Configuration as Code" is a concept where the configuration or settings of software is maintained in a Git repository as *code*.
75+
Contrast this with the approach where configuration is managed inside the software's own UI,
76+
making it hard to track changes, and copy settings to other projects.
77+
78+
Most users of Read the Docs will already be familiar with the concept since many popular tools already require you to store their configuration in your Git repository:
79+
80+
* Sphinx uses a ``conf.py`` file.
81+
* MkDocs uses a ``mkdocs.yaml`` file.
82+
* Python projects often have a ``requirements.txt`` or ``environment.yaml``.
83+
84+
Because of its fragility and uniqueness,
85+
the alternative to "Configuration as Code" is also often referred to as snowflake ❄️ configuration.
86+
Such configurations are hard to copy between projects and also hard to introspect for people without authorization to access the configuration UI.
87+
88+
*Configuration as code* is considered by many to be the easier option.
89+
It might seem harder to have to write the configuration code from scratch,
90+
but in order to use Read the Docs,
91+
you can usually start with a template and adapt it.
92+
93+
Read the Docs has chosen to offer as much configuration as possible through the usage of ``.readthedocs.yaml``.
94+
Our experience is that projects benefit from such a setup,
95+
and even when the benefits aren't obvious in the beginning of a project's lifecycle,
96+
they will emerge over time.
97+
98+
What's not covered by ``.readthedocs.yaml``?
99+
--------------------------------------------
100+
101+
There are a number of things that aren't possible to cover in the configuration file,
102+
which still belong in your project's Dashboard.
103+
104+
These configuration items are for instance:
105+
106+
Git settings
107+
Since the configuration file is stored in Git,
108+
it doesn't make sense that it would configure the Git setup.
109+
110+
Domain-level settings
111+
Since many settings apply to the domain a project is hosted on,
112+
they are configured for the project itself, and not a specific version.
21113

22-
Using a configuration file is the recommended way of using Read the Docs.
114+
The goal over time is to have everything that can be managed in a version-specific YAML file configured that way.
23115

24-
.. toctree::
25-
:maxdepth: 3
116+
.. seealso::
26117

27-
Version 2 <v2>
118+
:doc:`/guides/reproducible-builds`
119+
In addition to storing your configuration in Git,
120+
we also recommend special practices for making your builds resilient to changes in your software dependencies.

‎docs/user/config-file/v2.rst

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
1-
Configuration file v2
2-
=====================
1+
Configuration file v2 (.readthedocs.yaml)
2+
=========================================
33

4-
Read the Docs supports configuring your documentation builds with a YAML file.
5-
The :doc:`configuration file <index>` must be in the root directory of your project
6-
and be named ``.readthedocs.yaml``.
4+
Read the Docs supports configuring your documentation builds with a configuration file.
5+
This file is named ``.readthedocs.yaml`` and should be placed in the top level of your Git repository.
6+
7+
The ``.readthedocs.yaml`` file can contain a number of settings that are not accessible through the Read the Docs website.
8+
9+
Because the file is stored in Git,
10+
the configuration will apply to the exact version that is being built.
11+
**This allows you to store different configurations for different versions of your documentation.**
712

8-
All options are applied to the version containing this file.
913
Below is an example YAML file which shows the most common configuration options:
1014

1115
.. tabs::
@@ -25,6 +29,12 @@ Below is an example YAML file which shows the most common configuration options:
2529
:caption: .readthedocs.yaml
2630

2731

32+
.. seealso::
33+
34+
:doc:`/guides/setup/configuration-file`
35+
Practical steps to add a configuration file to your documentation project.
36+
37+
2838
Supported settings
2939
------------------
3040

@@ -902,3 +912,23 @@ These settings aren't supported via the configuration file.
902912
* ``Show versions warning``
903913
* ``Privacy level``
904914
* ``Analytics code``
915+
916+
Custom paths for .readthedocs.yaml
917+
----------------------------------
918+
919+
In order to support *monorepo* layouts,
920+
it's possible to configure the path to where your ``.readthedocs.yaml`` is found.
921+
922+
Using this configuration makes it possible to create several Read the Docs projects pointing at the same Git repository.
923+
This is recommended for monorepo layouts that host several documentation projects in the same repository.
924+
925+
.. seealso::
926+
927+
:doc:`/guides/setup/monorepo`
928+
This guide explains how to use the configuration.
929+
930+
Previous version: v1
931+
--------------------
932+
933+
Version 1 is deprecated and using it is discouraged,
934+
view its reference here :doc:`/config-file/v1`.

‎docs/user/explanation/advanced.rst

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
Deep dive into Read the Docs
2+
============================
3+
4+
In this section,
5+
we explain some of the more specific or advanced concepts of writing documentation on Read the Docs.
6+
7+
⏩️ :doc:`/config-file/index`
8+
An explanation of the value of having a versioned configuration file for your project.
9+
10+
⏩️ :doc:`/subprojects`
11+
*Subprojects* are a flexible for gathering multiple projects under the same domain.
12+
13+
⏩️ :doc:`/localization`
14+
Learn more about multilingual documentation projects and how translation workflows are supported.
15+
16+
⏩️ :doc:`/downloadable-documentation`
17+
An introduction to adding downloadable files, like PDFs, that can be read offline.
18+
19+
⏩️ :doc:`/environment-variables`
20+
Environment variables can be used to make your documentation builds flexible and easy to customize.
21+
22+
.. toctree::
23+
:maxdepth: 2
24+
:hidden:
25+
26+
/config-file/index
27+
/subprojects
28+
/localization
29+
/downloadable-documentation
30+
/environment-variables

‎docs/user/guides/manage-translations-sphinx.rst

Lines changed: 31 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -113,44 +113,59 @@ These features includes a great web based UI, `Translation Memory`_, collaborati
113113

114114
You need to create an account in their service and a new project before start.
115115

116-
After that, you need to install the `transifex-client`_ tool which will help you in the process to upload source files, update them and also download translated files.
116+
After that, you need to install the `Transifex CLI`_ tool which will help you in the process to upload source files, update them and also download translated files.
117117
To do this, run this command:
118118

119-
.. _transifex-client: https://docs.transifex.com/client/introduction
119+
.. _Transifex CLI: https://docs.transifex.com/client/introduction
120120

121121
.. prompt:: bash $
122122

123-
pip install transifex-client
123+
curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
124124

125125
After installing it, you need to configure your account.
126126
For this, you need to create an API Token for your user to access this service through the command line.
127127
This can be done under your `User's Settings`_.
128128

129-
.. _User's Settings: https://www.transifex.com/user/settings/api/
129+
.. _User's Settings: https://app.transifex.com/user/settings/api/
130130

131+
With the token, you have two options: to export as ``TX_TOKEN`` environment variable or to store it in ``~/.transifexrc``.
131132

132-
Now, you need to setup it to use this token:
133+
You can export the token to an environment variable, using an ``export`` command, which activates it in your current command line session:
133134

134135
.. prompt:: bash $
135136

136-
tx init --token $TOKEN --no-interactive
137+
# ``1/xxxx`` is the API token you generated
138+
export TX_TOKEN=1/xxxx
137139

140+
In order to store the token permanently, you can save it in a ``~/.transifexrc`` file. It should look like this:
138141

139-
The next step is to map every ``.pot`` file you have created in the previous step to a resource under Transifex.
142+
143+
.. code-block::
144+
145+
[https://www.transifex.com]
146+
rest_hostname = https://rest.api.transifex.com
147+
token = 1/xxxx
148+
149+
150+
Now, it is time to set the project's Transifex configuration and to map every ``.pot`` file you have created in the previous step to a resource under Transifex.
140151
To achieve this, you need to run this command:
141152

142153
.. prompt:: bash $
143154

144-
tx config mapping-bulk \
145-
--project $TRANSIFEX_PROJECT \
146-
--file-extension '.pot' \
147-
--source-file-dir docs/_build/gettext \
148-
--source-lang en \
149-
--type PO \
150-
--expression 'locale/<lang>/LC_MESSAGES/{filepath}/{filename}.po' \
151-
--execute
155+
sphinx-intl create-txconfig
156+
sphinx-intl update-txconfig-resources \
157+
--pot-dir _build/gettext \
158+
--locale-dir locale \
159+
--transifex-organization-name $TRANSIFEX_ORGANIZATION \
160+
--transifex-project-name $TRANSIFEX_PROJECT
161+
162+
163+
This command will generate a file at ``.tx/config`` with all the information needed by the ``tx`` tool to keep your translation synchronized.
164+
165+
.. seealso:
152166
153-
This command will generate a file at ``.tx/config`` with all the information needed by the ``transifext-client`` tool to keep your translation synchronized.
167+
`Transifex documentation for the tx command <https://developers.transifex.com/docs/using-the-client>`__
168+
If you prefer a more direct approach to setting up Transifex, you can also interact directly with the ``tx`` command
154169
155170
Finally, you need to upload these files to Transifex platform so translators can start their work.
156171
To do this, you can run this command:

‎docs/user/index.rst

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,7 @@ Read the Docs: documentation simplified
1919

2020
/choosing-a-site
2121
/integrations
22-
/downloadable-documentation
23-
/environment-variables
24-
/subprojects
25-
/localization
22+
/explanation/advanced
2623

2724
.. toctree::
2825
:maxdepth: 2
@@ -44,7 +41,7 @@ Read the Docs: documentation simplified
4441
:caption: 📚 Reference
4542

4643
/reference/features
47-
/config-file/index
44+
/config-file/v2
4845
/builds
4946
/build-customization
5047
/server-side-search/syntax
@@ -129,14 +126,12 @@ Get a high-level overview of our platform:
129126
💡 :doc:`/choosing-a-site`
130127
Learn about the differences between |org_brand| and |com_brand|.
131128

129+
💡 :doc:`/explanation/advanced`
130+
Get familiar with some of the more advanced topics of building and deploying documentation with Read the Docs.
131+
132132
💡 :doc:`All explanation articles </explanation/index>`
133133
Browser all our explanation articles.
134134

135-
.. TODO: This next item needs its article to be finished in a separate PR
136-
.. https://github.com/readthedocs/readthedocs.org/pull/10071
137-
.. TODO: 💡 Advanced topics: Deep-dive into Read the Docs
138-
.. Get familiar with some of the more advanced topics of building and deploying documentation with Read the Docs.
139-
140135

141136
How-to guides
142137
-------------
@@ -171,7 +166,7 @@ Here are a few of the most important reference docs:
171166
📚 :doc:`/reference/features`
172167
Overview of all the main features of Read the Docs.
173168

174-
📚 :doc:`/config-file/index`
169+
📚 :doc:`/config-file/v2`
175170
Information for our configuration file: ``.readthedocs.yaml``.
176171

177172
📚 :doc:`/builds`

‎readthedocs/api/v3/tests/test_builds.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,17 @@
33
from django.test import override_settings
44
from django.urls import reverse
55

6+
from readthedocs.subscriptions.constants import TYPE_CONCURRENT_BUILDS
7+
68
from .mixins import APIEndpointMixin
79

810

911
@override_settings(
1012
RTD_ALLOW_ORGANIZATIONS=False,
1113
ALLOW_PRIVATE_REPOS=False,
14+
RTD_DEFAULT_FEATURES={
15+
TYPE_CONCURRENT_BUILDS: 4,
16+
},
1217
)
1318
@mock.patch('readthedocs.projects.tasks.builds.update_docs_task', mock.MagicMock())
1419
class BuildsEndpointTests(APIEndpointMixin):

0 commit comments

Comments
 (0)