Bug 1805810 - Incremental improvements to source-docs building. r=dandarnell
Differential Revision: https://phabricator.services.mozilla.com/D164768 --HG-- extra : moz-landing-system : lando
This commit is contained in:
Rob Lemley
Родитель
7a7f369a7e
Коммит
1b3ebfa1f5
|
|
@ -1,3 +1,4 @@
|
|||
---
|
||||
# .readthedocs.yaml
|
||||
# Read the Docs configuration file
|
||||
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
|
||||
|
|
@ -7,9 +8,9 @@ version: 2
|
|||
|
||||
# Set the version of Python and other tools you might need
|
||||
build:
|
||||
os: ubuntu-20.04
|
||||
os: ubuntu-22.04
|
||||
tools:
|
||||
python: "3.9"
|
||||
python: "3.10"
|
||||
# You can also specify other tool versions:
|
||||
# nodejs: "16"
|
||||
# rust: "1.55"
|
||||
|
|
@ -17,13 +18,12 @@ build:
|
|||
|
||||
# Build documentation in the docs/ directory with Sphinx
|
||||
sphinx:
|
||||
configuration: docs/conf.py
|
||||
configuration: docs/conf.py
|
||||
|
||||
# If using Sphinx, optionally build your docs in additional formats such as PDF
|
||||
# formats:
|
||||
# - pdf
|
||||
|
||||
# Optionally declare the Python requirements required to build your docs
|
||||
#python:
|
||||
# install:
|
||||
# - requirements: docs/requirements.txt
|
||||
python:
|
||||
install:
|
||||
- requirements: docs/requirements.txt
|
||||
|
|
|
|||
|
|
@ -1,20 +1,32 @@
|
|||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
VENV = _venv
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SPHINXBUILD ?= ./$(VENV)/bin/sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
venv: Makefile
|
||||
python -m venv --upgrade-deps $(VENV)
|
||||
./$(VENV)/bin/pip install -r requirements.txt
|
||||
|
||||
|
||||
clean:
|
||||
@rm -rf $(VENV) $(BUILDDIR)
|
||||
|
||||
|
||||
.PHONY: help Makefile $(SPHINXBUILD)
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
%: $(SPHINXBUILD)
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,18 @@
|
|||
# Building documentation locally
|
||||
|
||||
This process will improve over time.
|
||||
|
||||
For now, manually create a Python virtual environment and install the
|
||||
dependencies:
|
||||
|
||||
```shell
|
||||
make venv
|
||||
```
|
||||
|
||||
The virtualenv will be created in **_venv**.
|
||||
|
||||
Then to build the documentation:
|
||||
|
||||
```shell
|
||||
make html
|
||||
```
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
# This Source Code Form is subject to the terms of the Mozilla Public
|
||||
# License, v. 2.0. If a copy of the MPL was not distributed with this
|
||||
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
||||
|
||||
import re
|
||||
|
||||
from docutils.nodes import Text, paragraph, reference
|
||||
from sphinx.transforms import SphinxTransform
|
||||
|
||||
|
||||
class ConvertBugsToLinks(SphinxTransform):
|
||||
# Convert text entries in paragraphs that are in the style of "bug xxxxx"
|
||||
# to a hyperlink that leads to the appropriate bugzilla bug link.
|
||||
|
||||
default_priority = 400
|
||||
bz_url = "https://bugzilla.mozilla.org/show_bug.cgi?id={0}"
|
||||
bz_reg = r"bug[' '][0-9]\d*"
|
||||
|
||||
def apply(self):
|
||||
def check_if_paragraph(o):
|
||||
return isinstance(o, paragraph)
|
||||
|
||||
def check_if_text(o):
|
||||
return (
|
||||
not isinstance(o.parent, reference)
|
||||
and isinstance(o, Text)
|
||||
and re.search(self.bz_reg, o, re.IGNORECASE)
|
||||
)
|
||||
|
||||
changed = True
|
||||
while changed:
|
||||
changed = self.textToReferences(check_if_paragraph, check_if_text)
|
||||
return
|
||||
|
||||
def textToReferences(self, check_if_paragraph, check_if_text):
|
||||
# Analyses the document and replaces from the paragraph nodes
|
||||
# the Text element(s) that contain bz_reg matching strings.
|
||||
# Whevever the matching strings are more than one and
|
||||
# a correction is made, the function returns True.
|
||||
|
||||
for node in self.document.traverse(check_if_paragraph):
|
||||
for text in node.traverse(check_if_text):
|
||||
bugs = re.findall(self.bz_reg, text, re.IGNORECASE)
|
||||
if len(bugs) == 0:
|
||||
continue
|
||||
bug = bugs[0]
|
||||
txtparts = text.split(bug, 1)
|
||||
new_ref = reference(
|
||||
bug,
|
||||
bug,
|
||||
refuri=self.bz_url.format(bug.split()[1]),
|
||||
)
|
||||
txt_0 = Text(txtparts[0])
|
||||
txt_1 = Text(txtparts[1])
|
||||
text.parent.replace(text, [txt_0, new_ref, txt_1])
|
||||
if len(bugs) > 1:
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def setup(app):
|
||||
app.add_transform(ConvertBugsToLinks)
|
||||
return
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
/* This Source Code Form is subject to the terms of the Mozilla Public
|
||||
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
||||
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
||||
|
||||
/* Increase the size of the content */
|
||||
.wy-nav-content {
|
||||
max-width: 80% !important;
|
||||
}
|
||||
|
||||
/* Increase the size of the tables */
|
||||
table.docutils {
|
||||
width: 90%;
|
||||
}
|
||||
|
||||
/* Override the default values for multiline text in a table */
|
||||
table.docutils td, table.docutils th
|
||||
{
|
||||
font-size: 16px !important;
|
||||
}
|
||||
|
||||
.rst-content .line-block {
|
||||
margin-bottom: 0px !important;
|
||||
}
|
||||
|
||||
/* Add the strikethrough feature */
|
||||
span.strikethrough {
|
||||
text-decoration: line-through;
|
||||
}
|
||||
|
||||
/* Better control over the table on this page */
|
||||
.matcher-cookbook td {
|
||||
white-space: break-spaces !important;
|
||||
}
|
||||
|
||||
.wy-table-responsive table td, .wy-table-responsive table th {
|
||||
white-space: normal;
|
||||
}
|
||||
|
||||
img.center {
|
||||
display: block;
|
||||
margin: auto;
|
||||
}
|
||||
|
||||
img.border {
|
||||
border: 1px solid black;
|
||||
display: block;
|
||||
margin: auto;
|
||||
}
|
||||
|
||||
.center {
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
/* Keyboard shortcuts styling */
|
||||
kbd {
|
||||
background: linear-gradient(180deg,#f4f4f4,#d5d5d5);
|
||||
background-color: #f4f4f4;
|
||||
border: 1px solid #d5d5d5;
|
||||
border-radius: 6px;
|
||||
font-family: consolas,"Liberation Mono",courier,monospace;
|
||||
font-size: .9rem;
|
||||
font-weight: 700;
|
||||
line-height: 2.3;
|
||||
margin: 3px;
|
||||
padding: 4px 6px 1px 6px;
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
table.docutils {
|
||||
width: 100%;
|
||||
}
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
<!-- This Source Code Form is subject to the terms of the Mozilla Public
|
||||
- License, v. 2.0. If a copy of the MPL was not distributed with this file,
|
||||
- You can obtain one at http://mozilla.org/MPL/2.0/. -->
|
||||
|
||||
{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
|
||||
|
||||
{% block breadcrumbs_aside %}
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Thunderbird&component=General&short_desc=Documentation+issue+on+{{ pagename }}&comment=URL+=+https://thunderbird-source-docs.readthedocs.io/{{ pagename }}.html&bug_file_loc=https://thunderbird-source-docs.readthedocs.io/{{ pagename }}.html" rel="nofollow">Report an issue</a> /
|
||||
{%- if show_source and has_source and sourcename %}
|
||||
<a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"> {{ _('View page source') }}</a>
|
||||
{%- endif %}
|
||||
</li>
|
||||
{% endblock %}
|
||||
62
docs/conf.py
62
docs/conf.py
|
|
@ -4,14 +4,66 @@
|
|||
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
|
||||
project = "Thunderbird"
|
||||
copyright = "2022, Mozilla"
|
||||
author = "Mozilla"
|
||||
import os
|
||||
import sys
|
||||
|
||||
extensions = []
|
||||
# Set up Python environment to load build system packages.
|
||||
OUR_DIR = os.path.dirname(__file__)
|
||||
topsrcdir = os.path.normpath(os.path.join(OUR_DIR, ".."))
|
||||
|
||||
|
||||
project = "Thunderbird Source Docs"
|
||||
html_show_copyright = False
|
||||
author = "Thunderbird Developers"
|
||||
|
||||
EXTRA_PATHS = ("docs/_addons",)
|
||||
|
||||
sys.path[:0] = [os.path.join(topsrcdir, p) for p in EXTRA_PATHS]
|
||||
|
||||
sys.path.insert(0, OUR_DIR)
|
||||
|
||||
extensions = [
|
||||
"myst_parser",
|
||||
"sphinx.ext.autodoc",
|
||||
"sphinx.ext.autosectionlabel",
|
||||
"sphinx.ext.doctest",
|
||||
"sphinx.ext.graphviz",
|
||||
"sphinx.ext.napoleon",
|
||||
"sphinx.ext.todo",
|
||||
"bzlink",
|
||||
]
|
||||
|
||||
myst_enable_extensions = [
|
||||
"deflist",
|
||||
"fieldlist",
|
||||
"html_admonition",
|
||||
"html_image",
|
||||
"linkify",
|
||||
"replacements",
|
||||
"smartquotes",
|
||||
"strikethrough",
|
||||
"tasklist",
|
||||
]
|
||||
|
||||
myst_linkify_fuzzy_links = False
|
||||
myst_heading_anchors = 2
|
||||
|
||||
templates_path = ["_templates"]
|
||||
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
|
||||
source_suffix = [".rst", ".md"]
|
||||
exclude_patterns = [
|
||||
"_build",
|
||||
"Thumbs.db",
|
||||
".DS_Store",
|
||||
"_staging",
|
||||
"_venv",
|
||||
"README.md",
|
||||
]
|
||||
|
||||
html_theme = "sphinx_rtd_theme"
|
||||
html_static_path = ["_static"]
|
||||
|
||||
autosectionlabel_maxdepth = 1
|
||||
|
||||
|
||||
def setup(app):
|
||||
app.add_css_file("custom_theme.css")
|
||||
|
|
|
|||
|
|
@ -0,0 +1,3 @@
|
|||
Sphinx>=5,<6
|
||||
sphinx_rtd_theme
|
||||
myst-parser[linkify]
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
#
|
||||
# This file is autogenerated by pip-compile with Python 3.10
|
||||
# by the following command:
|
||||
#
|
||||
# pip-compile requirements.in
|
||||
#
|
||||
alabaster==0.7.12
|
||||
# via sphinx
|
||||
babel==2.11.0
|
||||
# via sphinx
|
||||
certifi==2022.12.7
|
||||
# via requests
|
||||
charset-normalizer==2.1.1
|
||||
# via requests
|
||||
docutils==0.17.1
|
||||
# via
|
||||
# myst-parser
|
||||
# sphinx
|
||||
# sphinx-rtd-theme
|
||||
idna==3.4
|
||||
# via requests
|
||||
imagesize==1.4.1
|
||||
# via sphinx
|
||||
jinja2==3.1.2
|
||||
# via
|
||||
# myst-parser
|
||||
# sphinx
|
||||
linkify-it-py==1.0.3
|
||||
# via myst-parser
|
||||
markdown-it-py==2.1.0
|
||||
# via
|
||||
# mdit-py-plugins
|
||||
# myst-parser
|
||||
markupsafe==2.1.1
|
||||
# via jinja2
|
||||
mdit-py-plugins==0.3.3
|
||||
# via myst-parser
|
||||
mdurl==0.1.2
|
||||
# via markdown-it-py
|
||||
myst-parser[linkify]==0.18.1
|
||||
# via -r requirements.in
|
||||
packaging==22.0
|
||||
# via sphinx
|
||||
pygments==2.13.0
|
||||
# via sphinx
|
||||
pytz==2022.6
|
||||
# via babel
|
||||
pyyaml==6.0
|
||||
# via myst-parser
|
||||
requests==2.28.1
|
||||
# via sphinx
|
||||
snowballstemmer==2.2.0
|
||||
# via sphinx
|
||||
sphinx==5.3.0
|
||||
# via
|
||||
# -r requirements.in
|
||||
# myst-parser
|
||||
# sphinx-rtd-theme
|
||||
sphinx-rtd-theme==1.1.1
|
||||
# via -r requirements.in
|
||||
sphinxcontrib-applehelp==1.0.2
|
||||
# via sphinx
|
||||
sphinxcontrib-devhelp==1.0.2
|
||||
# via sphinx
|
||||
sphinxcontrib-htmlhelp==2.0.0
|
||||
# via sphinx
|
||||
sphinxcontrib-jsmath==1.0.1
|
||||
# via sphinx
|
||||
sphinxcontrib-qthelp==1.0.3
|
||||
# via sphinx
|
||||
sphinxcontrib-serializinghtml==1.1.5
|
||||
# via sphinx
|
||||
typing-extensions==4.4.0
|
||||
# via myst-parser
|
||||
uc-micro-py==1.0.1
|
||||
# via linkify-it-py
|
||||
urllib3==1.26.13
|
||||
# via requests
|
||||
Загрузка…
Ссылка в новой задаче