Skip to content

Commit 5d08d4e

Browse files
humitoshumitos
committed
Merge branch 'main' of github.com:readthedocs/readthedocs.org into humitos/build-jobs-config-object
2 parents 102534d + 052f891 commit 5d08d4e

File tree

5 files changed

+166
-140
lines changed

5 files changed

+166
-140
lines changed

‎docs/Makefile

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@
55
SPHINXOPTS =
66
SPHINXBUILD = sphinx-build
77
PAPER =
8-
BUILDDIR = _build/$(RTD_DOCSET)
8+
PROJECT ?= user
9+
BUILDDIR = _build/$(PROJECT)
910

1011
# Do not use local Django settings during the docs build
1112
export DJANGO_SETTINGS_SKIP_LOCAL = True

‎docs/conf.py

Lines changed: 112 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,23 @@
11
"""
2-
Shared Sphinx configuration.
2+
Shared Sphinx configuration using sphinx-multiproject.
33
4-
Each docset corresponds to a directory containing several rst/md files,
5-
sharing this same conf.py file. To build a docset an environment variable
6-
is used, ``RTD_DOCSET``, values given in the settings are relative to this
7-
conf.py file, if you want to give a different value for a docset, use the
8-
``docsets`` dictionary, or if you want to extend the current value,
9-
use f'{docset}/setting' as value on the setting, for example::
4+
To build each project, the ``PROJECT`` environment variable is used.
105
11-
html_static_path = ['_static', f'{docset}/_static']
6+
.. code:: console
7+
8+
$ make html # build default project
9+
$ PROJECT=dev make html # build the dev project
10+
11+
for more information read https://sphinx-multiproject.readthedocs.io/.
1212
"""
1313

1414
import os
1515
import sys
1616

1717
import sphinx_rtd_theme
18+
from multiproject.utils import get_project
1819

19-
sys.path.insert(0, os.path.abspath('..'))
20+
sys.path.insert(0, os.path.abspath(".."))
2021
sys.path.append(os.path.dirname(__file__))
2122
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "readthedocs.settings.dev")
2223

@@ -26,68 +27,72 @@
2627

2728
django.setup()
2829

29-
# Set here the variables you want for each docset.
30-
docsets = {
31-
'user': {
32-
'project': 'Read the Docs user documentation',
30+
sys.path.append(os.path.abspath("_ext"))
31+
extensions = [
32+
"multiproject",
33+
"sphinx.ext.autosectionlabel",
34+
"sphinx.ext.autodoc",
35+
"sphinx.ext.intersphinx",
36+
"sphinxcontrib.httpdomain",
37+
"djangodocs",
38+
"doc_extensions",
39+
"sphinx_tabs.tabs",
40+
"sphinx-prompt",
41+
"notfound.extension",
42+
"hoverxref.extension",
43+
"sphinx_search.extension",
44+
"sphinxemoji.sphinxemoji",
45+
"myst_parser",
46+
]
47+
48+
multiproject_projects = {
49+
"user": {
50+
"use_config_file": False,
51+
"config": {
52+
"project": "Read the Docs user documentation",
53+
},
3354
},
34-
'dev': {
35-
'project': 'Read the Docs developer documentation',
55+
"dev": {
56+
"use_config_file": False,
57+
"config": {
58+
"project": "Read the Docs developer documentation",
59+
},
3660
},
3761
}
38-
docset = os.environ.get('RTD_DOCSET', 'user')
39-
if docset not in docsets:
40-
print(f'Invalid RTD_DOCSET value: "{docset}"')
41-
exit(1)
4262

43-
for k, v in docsets[docset].items():
44-
locals()[k] = v
63+
docset = get_project(multiproject_projects)
4564

4665

47-
sys.path.append(os.path.abspath('_ext'))
48-
extensions = [
49-
'sphinx.ext.autosectionlabel',
50-
'sphinx.ext.autodoc',
51-
'sphinx.ext.intersphinx',
52-
'sphinxcontrib.httpdomain',
53-
'djangodocs',
54-
'doc_extensions',
55-
'sphinx_tabs.tabs',
56-
'sphinx-prompt',
57-
'notfound.extension',
58-
'hoverxref.extension',
59-
'sphinx_search.extension',
60-
'sphinxemoji.sphinxemoji',
61-
'myst_parser',
62-
]
63-
64-
templates_path = ['_templates']
66+
templates_path = ["_templates"]
6567

6668
master_doc = "index"
6769
copyright = "2010, Read the Docs, Inc & contributors"
6870
version = "7.5.0"
6971
release = version
70-
exclude_patterns = ['_build']
71-
default_role = 'obj'
72+
exclude_patterns = ["_build"]
73+
default_role = "obj"
7274
intersphinx_mapping = {
73-
'python': ('https://docs.python.org/3.6/', None),
74-
'django': ('https://docs.djangoproject.com/en/2.2/', 'https://docs.djangoproject.com/en/2.2/_objects/'),
75-
'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
76-
'pip': ('https://pip.pypa.io/en/stable/', None),
77-
'nbsphinx': ('https://nbsphinx.readthedocs.io/en/0.8.6/', None),
78-
'myst-nb': ('https://myst-nb.readthedocs.io/en/v0.12.3/', None),
79-
'ipywidgets': ('https://ipywidgets.readthedocs.io/en/7.6.3/', None),
80-
'jupytext': ('https://jupytext.readthedocs.io/en/stable/', None),
81-
'ipyleaflet': ('https://ipyleaflet.readthedocs.io/en/stable/', None),
82-
'poliastro': ('https://docs.poliastro.space/en/v0.15.2/', None),
83-
'qiskit': ('https://qiskit.org/documentation/', None),
84-
'myst-parser': ('https://myst-parser.readthedocs.io/en/v0.15.1/', None),
85-
'writethedocs': ('https://www.writethedocs.org/', None),
86-
'jupyterbook': ('https://jupyterbook.org/', None),
87-
'myst-parser': ('https://myst-parser.readthedocs.io/en/v0.15.1/', None),
88-
'rst-to-myst': ('https://rst-to-myst.readthedocs.io/en/stable/', None),
89-
'rtd': ('https://docs.readthedocs.io/en/stable/', None),
90-
'rtd-dev': ('https://dev.readthedocs.io/en/latest/', None),
75+
"python": ("https://docs.python.org/3.6/", None),
76+
"django": (
77+
"https://docs.djangoproject.com/en/2.2/",
78+
"https://docs.djangoproject.com/en/2.2/_objects/",
79+
),
80+
"sphinx": ("https://www.sphinx-doc.org/en/master/", None),
81+
"pip": ("https://pip.pypa.io/en/stable/", None),
82+
"nbsphinx": ("https://nbsphinx.readthedocs.io/en/0.8.6/", None),
83+
"myst-nb": ("https://myst-nb.readthedocs.io/en/v0.12.3/", None),
84+
"ipywidgets": ("https://ipywidgets.readthedocs.io/en/7.6.3/", None),
85+
"jupytext": ("https://jupytext.readthedocs.io/en/stable/", None),
86+
"ipyleaflet": ("https://ipyleaflet.readthedocs.io/en/stable/", None),
87+
"poliastro": ("https://docs.poliastro.space/en/v0.15.2/", None),
88+
"qiskit": ("https://qiskit.org/documentation/", None),
89+
"myst-parser": ("https://myst-parser.readthedocs.io/en/v0.15.1/", None),
90+
"writethedocs": ("https://www.writethedocs.org/", None),
91+
"jupyterbook": ("https://jupyterbook.org/", None),
92+
"myst-parser": ("https://myst-parser.readthedocs.io/en/v0.15.1/", None),
93+
"rst-to-myst": ("https://rst-to-myst.readthedocs.io/en/stable/", None),
94+
"rtd": ("https://docs.readthedocs.io/en/stable/", None),
95+
"rtd-dev": ("https://dev.readthedocs.io/en/latest/", None),
9196
}
9297
myst_enable_extensions = [
9398
"deflist",
@@ -100,56 +105,66 @@
100105
"ipywidgets",
101106
"jupytext",
102107
]
103-
htmlhelp_basename = 'ReadTheDocsdoc'
108+
htmlhelp_basename = "ReadTheDocsdoc"
104109
latex_documents = [
105-
('index', 'ReadTheDocs.tex', 'Read the Docs Documentation',
106-
'Eric Holscher, Charlie Leifer, Bobby Grace', 'manual'),
110+
(
111+
"index",
112+
"ReadTheDocs.tex",
113+
"Read the Docs Documentation",
114+
"Eric Holscher, Charlie Leifer, Bobby Grace",
115+
"manual",
116+
),
107117
]
108118
man_pages = [
109-
('index', 'read-the-docs', 'Read the Docs Documentation',
110-
['Eric Holscher, Charlie Leifer, Bobby Grace'], 1)
119+
(
120+
"index",
121+
"read-the-docs",
122+
"Read the Docs Documentation",
123+
["Eric Holscher, Charlie Leifer, Bobby Grace"],
124+
1,
125+
)
111126
]
112127

113128
exclude_patterns = [
114129
# 'api' # needed for ``make gettext`` to not die.
115130
]
116131

117-
language = 'en'
132+
language = "en"
118133

119134
locale_dirs = [
120-
f'{docset}/locale/',
135+
f"{docset}/locale/",
121136
]
122137
gettext_compact = False
123138

124-
html_theme = 'sphinx_rtd_theme'
125-
html_static_path = ['_static', f'{docset}/_static']
126-
html_css_files = ['css/custom.css', 'css/sphinx_prompt_css.css']
127-
html_js_files = ['js/expand_tabs.js']
139+
html_theme = "sphinx_rtd_theme"
140+
html_static_path = ["_static", f"{docset}/_static"]
141+
html_css_files = ["css/custom.css", "css/sphinx_prompt_css.css"]
142+
html_js_files = ["js/expand_tabs.js"]
128143
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
129-
html_logo = 'img/logo.svg'
144+
html_logo = "img/logo.svg"
130145
html_theme_options = {
131-
'logo_only': True,
132-
'display_version': False,
146+
"logo_only": True,
147+
"display_version": False,
133148
}
134149
html_context = {
135150
# Fix the "edit on" links.
136151
# TODO: remove once we support different rtd config
137152
# files per project.
138-
'conf_py_path': f'/docs/{docset}/',
153+
"conf_py_path": f"/docs/{docset}/",
139154
}
140155

141156
hoverxref_auto_ref = True
142-
hoverxref_domains = ['py']
157+
hoverxref_domains = ["py"]
143158
hoverxref_roles = [
144-
'option',
145-
'doc',
159+
"option",
160+
"doc",
146161
]
147162
hoverxref_role_types = {
148-
'mod': 'modal', # for Python Sphinx Domain
149-
'doc': 'modal', # for whole docs
150-
'class': 'tooltip', # for Python Sphinx Domain
151-
'ref': 'tooltip', # for hoverxref_auto_ref config
152-
'confval': 'tooltip', # for custom object
163+
"mod": "modal", # for Python Sphinx Domain
164+
"doc": "modal", # for whole docs
165+
"class": "tooltip", # for Python Sphinx Domain
166+
"ref": "tooltip", # for hoverxref_auto_ref config
167+
"confval": "tooltip", # for custom object
153168
}
154169

155170
rst_epilog = """
@@ -163,31 +178,27 @@
163178
# sphinx-notfound-page
164179
# https://github.com/readthedocs/sphinx-notfound-page
165180
notfound_context = {
166-
'title': 'Page Not Found',
167-
'body': '''
181+
"title": "Page Not Found",
182+
"body": """
168183
<h1>Page Not Found</h1>
169184
170185
<p>Sorry, we couldn't find that page.</p>
171186
172187
<p>Try using the search box or go to the homepage.</p>
173-
''',
188+
""",
174189
}
175190
linkcheck_ignore = [
176-
r'http://127\.0\.0\.1',
177-
r'http://localhost',
178-
r'http://community\.dev\.readthedocs\.io',
179-
r'https://yourproject\.readthedocs\.io',
180-
r'https?://docs\.example\.com',
181-
r'https://foo\.readthedocs\.io/projects',
182-
r'https://github\.com.+?#L\d+',
183-
r'https://github\.com/readthedocs/readthedocs\.org/issues',
184-
r'https://github\.com/readthedocs/readthedocs\.org/pull',
185-
r'https://docs\.readthedocs\.io/\?rtd_search',
186-
r'https://readthedocs\.org/search',
191+
r"http://127\.0\.0\.1",
192+
r"http://localhost",
193+
r"http://community\.dev\.readthedocs\.io",
194+
r"https://yourproject\.readthedocs\.io",
195+
r"https?://docs\.example\.com",
196+
r"https://foo\.readthedocs\.io/projects",
197+
r"https://github\.com.+?#L\d+",
198+
r"https://github\.com/readthedocs/readthedocs\.org/issues",
199+
r"https://github\.com/readthedocs/readthedocs\.org/pull",
200+
r"https://docs\.readthedocs\.io/\?rtd_search",
201+
r"https://readthedocs\.org/search",
187202
# This page is under login
188-
r'https://readthedocs\.org/accounts/gold',
203+
r"https://readthedocs\.org/accounts/gold",
189204
]
190-
191-
192-
def setup(app):
193-
app.srcdir += '/' + docset

‎readthedocs/doc_builder/director.py

Lines changed: 31 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,37 @@ def setup_vcs(self):
6565
),
6666
)
6767

68+
before_vcs.send(
69+
sender=self.data.version,
70+
environment=self.vcs_environment,
71+
)
72+
73+
# Create the VCS repository where all the commands are going to be
74+
# executed for a particular VCS type
75+
self.vcs_repository = self.data.project.vcs_repo(
76+
version=self.data.version.slug,
77+
environment=self.vcs_environment,
78+
verbose_name=self.data.version.verbose_name,
79+
version_type=self.data.version.type,
80+
)
81+
82+
# We can't do too much on ``pre_checkout`` because we haven't
83+
# cloned the repository yet and we don't know what the user wrote
84+
# in the `.readthedocs.yaml` yet.
85+
#
86+
# We could implement something different in the future if we download
87+
# the `.readthedocs.yaml` file without cloning.
88+
# See https://github.com/readthedocs/readthedocs.org/issues/8935
89+
#
90+
# self.run_build_job("pre_checkout")
91+
self.checkout()
92+
self.run_build_job("post_checkout")
93+
94+
commit = self.data.build_commit or self.vcs_repository.commit
95+
if commit:
96+
self.data.build["commit"] = commit
97+
98+
def create_vcs_environment(self):
6899
self.vcs_environment = self.data.environment_class(
69100
project=self.data.project,
70101
version=self.data.version,
@@ -74,37 +105,6 @@ def setup_vcs(self):
74105
# ca-certificate package which is compatible with Lets Encrypt
75106
container_image=settings.RTD_DOCKER_BUILD_SETTINGS["os"]["ubuntu-20.04"],
76107
)
77-
with self.vcs_environment:
78-
before_vcs.send(
79-
sender=self.data.version,
80-
environment=self.vcs_environment,
81-
)
82-
83-
# Create the VCS repository where all the commands are going to be
84-
# executed for a particular VCS type
85-
self.vcs_repository = self.data.project.vcs_repo(
86-
version=self.data.version.slug,
87-
environment=self.vcs_environment,
88-
verbose_name=self.data.version.verbose_name,
89-
version_type=self.data.version.type,
90-
)
91-
92-
# We can't do too much on ``pre_checkout`` because we haven't
93-
# cloned the repository yet and we don't know what the user wrote
94-
# in the `.readthedocs.yaml` yet.
95-
#
96-
# We could implement something different in the future if we download
97-
# the `.readthedocs.yaml` file without cloning.
98-
# See https://github.com/readthedocs/readthedocs.org/issues/8935
99-
#
100-
# self.run_build_job('pre_checkout')
101-
102-
self.checkout()
103-
self.run_build_job("post_checkout")
104-
105-
commit = self.data.build_commit or self.vcs_repository.commit
106-
if commit:
107-
self.data.build["commit"] = commit
108108

109109
def create_build_environment(self):
110110
self.build_environment = self.data.environment_class(

0 commit comments

Comments
 (0)