Skip to content

Commit 1bd6a69

Browse files
benjaomingbenjaoming
committed
Merge branch 'main' of github.com:readthedocs/readthedocs.org into multi_config
2 parents 89fc389 + dd07a3e commit 1bd6a69

File tree

481 files changed

+15172
-12347
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

481 files changed

+15172
-12347
lines changed

‎.circleci/config.yml

-1
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,6 @@ jobs:
4646
- run: pip install --user 'tox<5'
4747
- run: tox -e pre-commit
4848
- run: tox -e migrations
49-
- run: tox -e lint
5049
- run: scripts/circle/install_node.sh
5150
- run:
5251
name: Add node to the path

‎.github/config.yml

-1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,3 @@ todo:
66
blobLines: 7
77
caseSensitive: true
88
keyword: "TODO"
9-

‎.github/workflows/pip-tools.yaml

-3
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,6 @@ jobs:
3939
- name: Run pip-compile on requirements/testing.in
4040
run: pip-compile --upgrade --resolver=backtracking --output-file=requirements/testing.txt requirements/testing.in
4141

42-
- name: Run pip-compile on requirements/lint.in
43-
run: pip-compile --upgrade --resolver=backtracking --output-file=requirements/lint.txt requirements/lint.in
44-
4542
- name: Run pip-compile on requirements/docs.in
4643
run: pip-compile --upgrade --resolver=backtracking --output-file=requirements/docs.txt requirements/docs.in
4744

‎CHANGELOG.rst

+124-2
Large diffs are not rendered by default.

‎LICENSE

-1
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,3 @@ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
2020
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
2121
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
2222
OTHER DEALINGS IN THE SOFTWARE.
23-

‎common

‎docker-compose.override.yml

+9-3
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,6 @@ services:
2727
GITHUB_USER: ${GITHUB_USER:-}
2828
GITHUB_TOKEN: ${GITHUB_TOKEN:-}
2929

30-
cache:
31-
image: redis:6.0.5
32-
3330
nginx:
3431
networks:
3532
readthedocs:
@@ -66,6 +63,15 @@ services:
6663
- DJANGO_SETTINGS_MODULE=readthedocs.settings.celery_docker
6764
- CELERY_APP_NAME=readthedocs
6865

66+
celery-beat:
67+
image: community_server:latest
68+
volumes:
69+
- ${PWD}:/usr/src/app/checkouts/readthedocs.org
70+
- ${PWD}/dockerfiles/settings/celery.py:/usr/src/app/checkouts/readthedocs.org/readthedocs/settings/celery_docker.py
71+
environment:
72+
- DJANGO_SETTINGS_MODULE=readthedocs.settings.celery_docker
73+
- CELERY_APP_NAME=readthedocs
74+
6975
build:
7076
image: community_server:latest
7177
volumes:

‎dockerfiles/nginx/proxito.conf.template

+2
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,8 @@ server {
8282
add_header Access-Control-Allow-Headers $access_control_allow_headers always;
8383
set $x_frame_options $upstream_http_x_frame_options;
8484
add_header X-Frame-Options $x_frame_options always;
85+
set $x_content_type_options $upstream_http_x_content_type_options;
86+
add_header X-Content-Type-Options $x_content_type_options always;
8587
# Minio sets this header on the response, and we don't want to copy it to the response
8688
proxy_hide_header Content-Security-Policy;
8789
set $content_security_policy $upstream_http_content_security_policy;

‎dockerfiles/settings/proxito.py

+2
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
class ProxitoDevSettings(CommunityProxitoSettingsMixin, DockerBaseSettings):
77
DONT_HIT_DB = False
88

9+
CACHEOPS_ENABLED = True
10+
911
# El Proxito does not have django-debug-toolbar installed
1012
@property
1113
def DEBUG_TOOLBAR_CONFIG(self):

‎docs/_static/css/custom.css

+12
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,15 @@
99
#rtd-stickybox-container {
1010
text-align: center;
1111
}
12+
13+
.wy-menu.wy-menu-vertical a.reference.external::after {
14+
/* \00a0 = no break space */
15+
content: "\00a0\f08e";
16+
font-family: FontAwesome;
17+
display: inline-block;
18+
font-style: normal;
19+
font-variant: normal;
20+
text-rendering: auto;
21+
-webkit-font-smoothing: antialiased;
22+
23+
}

‎docs/_static/img/logo-opengraph.png

20.6 KB
Loading

‎docs/_static/js/expand_tabs.js

+25-3
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
11
/*
22
* Expands a specific tab of sphinx-tabs.
33
* Usage:
4-
* - docs.readthedocs.io/?tab=Name
5-
* - docs.readthedocs.io/?tab=Name#section
6-
* Where 'Name' is the title of the tab (case sensitive).
4+
* 1) docs.readthedocs.io/?tab=Name
5+
* 2) docs.readthedocs.io/?tab=Name#section
6+
* 3) docs.readthedocs.io/page#sphinx-label
7+
* In 1) and 2), 'Name' is the title of the tab (case sensitive).
8+
*
9+
* In 3), you need to add a sphinx reference inside the tab.
10+
* It mimics how sections are referenced and can be refactored.
711
*/
812
$( document ).ready(function() {
913
const urlParams = new URLSearchParams(window.location.search);
@@ -14,4 +18,22 @@ $( document ).ready(function() {
1418
tab.click();
1519
}
1620
}
21+
22+
// Uses a hash referencing a Sphinx label from the URL page#sphinx-label
23+
var hash = window.location.hash.substr(1);
24+
if (hash) {
25+
hash = hash.replace(/[^0-9a-z\-_]/gi, '');
26+
// If the hash is inside a tab panel
27+
var tab_with_reference = $(".sphinx-tabs-panel #" + hash).parents(".sphinx-tabs-panel");
28+
29+
if (tab_with_reference.length > 0) {
30+
// Use the panel's ID to guess the tab's ID
31+
var panel_id = tab_with_reference.first().attr("id");
32+
var tab_id = panel_id.replace("panel-", "tab-");
33+
// Invoke the tab buttons click() method to display it
34+
$("button#" + tab_id).click();
35+
// Scroll the tab widget into view
36+
$('html, body').animate({ scrollTop: tab_with_reference.parents(".sphinx-tabs").first().offset().top}, 1000);
37+
}
38+
}
1739
});

‎docs/_static/js/readthedocs-doc-diff.js

+1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/_templates/layout.html

+7
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
{% extends "!layout.html" %}
22

3+
{% block extrahead %}
4+
{{ super() }}
5+
6+
{% if READTHEDOCS %}
7+
<script defer data-domain="{{ plausible_domain }}" src="https://plausible.io/js/script.js"></script>
8+
{% endif %}
9+
{% endblock extrahead %}
310

411
{% block document %}
512
{{ super() }}

‎docs/conf.py

+45-14
Original file line numberDiff line numberDiff line change
@@ -18,20 +18,22 @@
1818

1919
sys.path.append(os.path.abspath("_ext"))
2020
extensions = [
21+
"hoverxref.extension",
2122
"multiproject",
22-
"sphinx.ext.autosectionlabel",
23+
"myst_parser",
24+
"notfound.extension",
25+
"sphinx_design",
26+
"sphinx_search.extension",
27+
"sphinx_tabs.tabs",
28+
"sphinx-prompt",
2329
"sphinx.ext.autodoc",
30+
"sphinx.ext.autosectionlabel",
31+
"sphinx.ext.extlinks",
2432
"sphinx.ext.intersphinx",
2533
"sphinxcontrib.httpdomain",
2634
"sphinxcontrib.video",
27-
"sphinx_tabs.tabs",
28-
"sphinx-prompt",
29-
"notfound.extension",
30-
"hoverxref.extension",
31-
"sphinx_search.extension",
3235
"sphinxemoji.sphinxemoji",
33-
"sphinx_design",
34-
"myst_parser",
36+
"sphinxext.opengraph",
3537
]
3638

3739
multiproject_projects = {
@@ -51,15 +53,25 @@
5153

5254
docset = get_project(multiproject_projects)
5355

56+
ogp_site_name = "Read the Docs Documentation"
57+
ogp_use_first_image = True # https://github.com/readthedocs/blog/pull/118
58+
ogp_image = "https://docs.readthedocs.io/en/latest/_static/img/logo-opengraph.png"
59+
# Inspired by https://github.com/executablebooks/MyST-Parser/pull/404/
60+
ogp_custom_meta_tags = [
61+
'<meta name="twitter:card" content="summary_large_image" />',
62+
]
63+
ogp_enable_meta_description = True
64+
ogp_description_length = 300
5465

5566
templates_path = ["_templates"]
5667

5768
master_doc = "index"
5869
copyright = "Read the Docs, Inc & contributors"
59-
version = "9.4.0"
70+
version = "9.8.0"
6071
release = version
61-
exclude_patterns = ["_build", "shared"]
72+
exclude_patterns = ["_build", "shared", "_includes"]
6273
default_role = "obj"
74+
intersphinx_cache_limit = 14 # cache for 2 weeks
6375
intersphinx_timeout = 3 # 3 seconds timeout
6476
intersphinx_mapping = {
6577
"python": ("https://docs.python.org/3.10/", None),
@@ -85,9 +97,16 @@
8597
"rtd-dev": ("https://dev.readthedocs.io/en/latest/", None),
8698
"jupyter": ("https://docs.jupyter.org/en/latest/", None),
8799
}
88-
# Redundant in Sphinx 5.0
100+
101+
# Intersphinx: Do not try to resolve unresolved labels that aren't explicitly prefixed.
102+
# The default setting for intersphinx_disabled_reftypes can cause some pretty bad
103+
# breakage because we have rtd and rtd-dev stable versions in our mappings.
104+
# Hence, if we refactor labels, we won't see broken references, since the
105+
# currently active stable mapping keeps resolving.
106+
# Recommending doing this on all projects with Intersphinx.
89107
# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes
90-
intersphinx_disabled_reftypes = ["std:doc"]
108+
intersphinx_disabled_reftypes = ["*"]
109+
91110
myst_enable_extensions = [
92111
"deflist",
93112
]
@@ -131,6 +150,9 @@
131150
html_css_files = ["css/custom.css", "css/sphinx_prompt_css.css"]
132151
html_js_files = ["js/expand_tabs.js"]
133152

153+
if os.environ.get("READTHEDOCS_VERSION_TYPE") == "external":
154+
html_js_files.append("js/readthedocs-doc-diff.js")
155+
134156
html_logo = "img/logo.svg"
135157
html_theme_options = {
136158
"logo_only": True,
@@ -141,14 +163,19 @@
141163
# TODO: remove once we support different rtd config
142164
# files per project.
143165
"conf_py_path": f"/docs/{docset}/",
166+
# Use to generate the Plausible "data-domain" attribute from the template
167+
"plausible_domain": f"{os.environ.get('READTHEDOCS_PROJECT')}.readthedocs.io",
144168
}
145169

146170
hoverxref_auto_ref = True
147171
hoverxref_domains = ["py"]
148172
hoverxref_roles = [
149173
"option",
150-
"doc", # Documentation pages
151-
"term", # Glossary terms
174+
# Documentation pages
175+
# Not supported yet: https://github.com/readthedocs/sphinx-hoverxref/issues/18
176+
"doc",
177+
# Glossary terms
178+
"term",
152179
]
153180
hoverxref_role_types = {
154181
"mod": "modal", # for Python Sphinx Domain
@@ -201,5 +228,9 @@
201228
r"https://readthedocs\.org/accounts/gold",
202229
]
203230

231+
extlinks = {
232+
"rtd-issue": ("https://github.com/readthedocs/readthedocs.org/issues/%s", "#%s"),
233+
}
234+
204235
# Disable epub mimetype warnings
205236
suppress_warnings = ["epub.unknown_project_files"]

‎docs/dev/design.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ to get a working copy of the Read the Docs repository locally.
1212

1313
.. TODO: update to match the new ext-theme
1414
15-
Style Catalog
15+
Style catalog
1616
-------------
1717

1818
Once you have RTD running locally, you can open ``http://localhost:8000/style-catalog/``
@@ -24,7 +24,7 @@ This way you can quickly get started writing HTML -- or if you're
2424
modifying existing styles you can get a quick idea of how things
2525
will change site-wide.
2626

27-
Readthedocs.org Changes
27+
Readthedocs.org changes
2828
-----------------------
2929

3030
Styles for the primary RTD site are located in ``media/css`` directory.
@@ -44,7 +44,7 @@ There's not a hard browser range, but your design changes should work reasonably
4444
browsers, IE8+ -- that's not to say it needs to be pixel-perfect in older browsers! Just avoid
4545
making changes that render older browsers utterly unusable (or provide a sane fallback).
4646

47-
Brand Guidelines
47+
Brand guidelines
4848
----------------
4949

5050
Find our branding guidelines in our guidelines documentation: https://read-the-docs-guidelines.readthedocs-hosted.com.

‎docs/dev/design/apiv3.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
======================
2-
API v3 Design Document
2+
API v3 design document
33
======================
44

55
This document describes the design,

‎docs/dev/design/build-images.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Build Images
1+
Build images
22
============
33

44
This document describes how Read the Docs uses the `Docker Images`_ and how they are named.

‎docs/dev/design/future-builder.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Future Builder
1+
Future builder
22
==============
33

44
.. contents::

‎docs/dev/design/in-doc-search-ui.rst

+11-11
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
In Doc Search UI
1+
In-doc search UI
22
================
33

44
Giving readers the ability to easily search the information
@@ -24,34 +24,34 @@ The final result may look something like this:
2424
Short demo
2525

2626

27-
Goals And Non-Goals
27+
Goals And non-Goals
2828
-------------------
2929

30-
Project Goals
31-
++++++++++++++
30+
Project goals
31+
+++++++++++++
3232

3333
* Support a search-as-you-type/autocomplete interface.
3434
* Support across all (or virtually all) Sphinx themes.
3535
* Support for the JavaScript user experience down to IE11 or graceful degradation where we can't support it.
3636
* Project maintainers should have a way to opt-in/opt-out of this feature.
3737
* (Optional) Project maintainers should have the flexibility to change some of the styles using custom CSS and JS files.
3838

39-
Non-Goals
40-
++++++++++
39+
Non-goals
40+
+++++++++
4141

4242
* For the initial release, we are targeting only Sphinx documentations
4343
as we don't index MkDocs documentations to our Elasticsearch index.
4444

4545

46-
Existing Search Implementation
46+
Existing search implementation
4747
------------------------------
4848

4949
We have a detailed documentation explaining the underlying architecture of our search backend
5050
and how we index documents to our Elasticsearch index.
5151
You can read about it :doc:`here </server-side-search>`.
5252

5353

54-
Proposed Architecture for In-Doc Search UI
54+
Proposed architecture for in-doc search UI
5555
------------------------------------------
5656

5757
Frontend
@@ -69,7 +69,7 @@ This will provide us some advantages over using any third party library:
6969
* Performance benefits.
7070

7171

72-
Proposed Architecture
72+
Proposed architecture
7373
~~~~~~~~~~~~~~~~~~~~~
7474

7575
We plan to select the search bar, which is present in every theme,
@@ -125,7 +125,7 @@ Edge NGram Tokenizer
125125
* Requires greater disk space.
126126

127127

128-
Completion Suggester
128+
Completion suggester
129129
~~~~~~~~~~~~~~~~~~~~
130130

131131
* Pros
@@ -164,7 +164,7 @@ Milestones
164164
+-----------------------------------------------------------------------------------+------------------+
165165

166166

167-
Open Questions
167+
Open questions
168168
++++++++++++++
169169

170170
* Should we rely on jQuery, any third party library or pure vanilla JavaScript?

0 commit comments

Comments
 (0)