Docs: update tooling and outdated/broken content

* Update docs build config
  * Specify Sphinx and theme versions in docs/requirements.txt
    (tox had been using latest; RTD had pinned older versions)
  * Update docs builds for Python 3 and recent Sphinx
  * Remove obsolete sphinx-rtd-theme patches
  * Add .readthedocs.yml
  * Move some JS to async (now that Sphinx supports that)
  * Fix version-alert.js for async loading
* Remove docs versionadded/changed info older than v3.0
* Fix broken GitHub issue links in changelog (never worked?)
* Add setup long_description_content_type
* Drop poorly maintained AUTHORS.txt 
  (just point to GitHub contributors page)
This commit is contained in:
Mike Edmunds
2020-09-07 12:05:39 -07:00
committed by GitHub
parent 963b8b4b50
commit cca653fcba
19 changed files with 102 additions and 159 deletions

View File

@@ -11,20 +11,25 @@
import os
import sys
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
from pathlib import Path
ON_READTHEDOCS = os.environ.get('READTHEDOCS', None) == 'True'
DOCS_PATH = Path(__file__).parent
PROJECT_ROOT_PATH = DOCS_PATH.parent
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, PROJECT_ROOT_PATH.resolve())
# define __version__ and __minor_version__ from ../anymail/_version.py,
# but without importing from anymail (which would make docs dependent on Django, etc.)
__version__ = "UNSET"
__minor_version__ = "UNSET"
with open("../anymail/_version.py") as f:
code = compile(f.read(), "../anymail/_version.py", 'exec')
exec(code)
version_path = PROJECT_ROOT_PATH / "anymail/_version.py"
code = compile(version_path.read_text(), version_path, 'exec')
exec(code)
# -- General configuration -----------------------------------------------------
@@ -50,7 +55,7 @@ master_doc = 'index'
# General information about the project.
project = 'Anymail'
# noinspection PyShadowingBuiltins
copyright = 'Anymail contributors (see AUTHORS.txt)'
copyright = 'Anymail contributors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -100,11 +105,11 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
if not on_rtd: # only import and set the theme if we're building docs locally
if not ON_READTHEDOCS: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme # this seems to come with sphinx; if not, pip install it
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# if on_rtd, readthedocs.org uses their theme by default (and specifying it here breaks them)
# else readthedocs.org uses their theme by default (and specifying it here breaks them)
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@@ -202,7 +207,7 @@ latex_elements = {
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'Anymail.tex', 'Anymail Documentation',
'Anymail contributors (see AUTHORS.txt)', 'manual'),
'Anymail contributors', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
@@ -232,7 +237,7 @@ latex_documents = [
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'anymail', 'Anymail Documentation',
['Anymail contributors (see AUTHORS.txt)'], 1)
['Anymail contributors'], 1)
]
# If true, show URL addresses after external links.
@@ -246,7 +251,7 @@ man_pages = [
# dir menu entry, description, category)
texinfo_documents = [
('index', 'Anymail', 'Anymail Documentation',
'Anymail contributors (see AUTHORS.txt)', 'Anymail', 'Multi-ESP transactional email for Django.',
'Anymail contributors', 'Anymail', 'Multi-ESP transactional email for Django.',
'Miscellaneous'),
]
@@ -275,10 +280,13 @@ intersphinx_mapping = {
def setup(app):
app.add_stylesheet("anymail-theme.css")
app.add_javascript("anymail-config.js")
app.add_javascript("version-alert.js")
app.add_javascript("https://unpkg.com/rate-the-docs")
app.add_css_file("anymail-theme.css")
# Inline <script> for anymail-config.js to avoid non-async JS load:
# app.add_js_file("anymail-config.js")
anymail_config_js = (DOCS_PATH / "_static/anymail-config.js").read_text()
app.add_js_file(None, body=anymail_config_js)
app.add_js_file("version-alert.js", **{"async": "async"})
app.add_js_file("https://unpkg.com/rate-the-docs", **{"async": "async"})
# Django-specific roles, from https://github.com/django/django/blob/master/docs/_ext/djangodocs.py:
app.add_crossref_type(