diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 9c5593381a..b9f7296c5f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -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 diff --git a/docs/Makefile b/docs/Makefile index d4bb2cbb9e..a9bc6a02c3 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -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) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..4ffb083903 --- /dev/null +++ b/docs/README.md @@ -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 +``` diff --git a/docs/_addons/bzlink.py b/docs/_addons/bzlink.py new file mode 100644 index 0000000000..6bdbdac8c5 --- /dev/null +++ b/docs/_addons/bzlink.py @@ -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 diff --git a/docs/_static/custom_theme.css b/docs/_static/custom_theme.css new file mode 100644 index 0000000000..c8e34c03ca --- /dev/null +++ b/docs/_static/custom_theme.css @@ -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%; +} diff --git a/docs/_templates/breadcrumbs.html b/docs/_templates/breadcrumbs.html new file mode 100644 index 0000000000..27bf66b65b --- /dev/null +++ b/docs/_templates/breadcrumbs.html @@ -0,0 +1,14 @@ + + +{%- extends "sphinx_rtd_theme/breadcrumbs.html" %} + +{% block breadcrumbs_aside %} +
  • + Report an issue / + {%- if show_source and has_source and sourcename %} + {{ _('View page source') }} + {%- endif %} +
    • +{% endblock %} diff --git a/docs/conf.py b/docs/conf.py index 81c9d43270..fc9c1fb9b3 100644 --- a/docs/conf.py +++ b/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") diff --git a/docs/requirements.in b/docs/requirements.in new file mode 100644 index 0000000000..fb04ecfacb --- /dev/null +++ b/docs/requirements.in @@ -0,0 +1,3 @@ +Sphinx>=5,<6 +sphinx_rtd_theme +myst-parser[linkify] diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000000..0141b2ab20 --- /dev/null +++ b/docs/requirements.txt @@ -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