mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-07 10:04:07 +00:00
docs: refresh conf.py for readability
This commit is contained in:
Erik Sundell
@@ -1,59 +1,68 @@
|
||||
# Configuration file for Sphinx to build our documentation to HTML.
|
||||
#
|
||||
# Configuration reference: https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
#
|
||||
import contextlib
|
||||
import datetime
|
||||
import io
|
||||
import os
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
# Sphinx extension modules
|
||||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
'sphinx.ext.intersphinx',
|
||||
'sphinx.ext.napoleon',
|
||||
'autodoc_traits',
|
||||
'sphinx_copybutton',
|
||||
'sphinx-jsonschema',
|
||||
'myst_parser',
|
||||
]
|
||||
|
||||
myst_heading_anchors = 2
|
||||
myst_enable_extensions = [
|
||||
'colon_fence',
|
||||
'deflist',
|
||||
]
|
||||
# The master toctree document.
|
||||
root_doc = master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = 'JupyterHub'
|
||||
copyright = '2016, Project Jupyter team'
|
||||
author = 'Project Jupyter team'
|
||||
|
||||
# Autopopulate version
|
||||
import jupyterhub
|
||||
|
||||
# The short X.Y version.
|
||||
version = '%i.%i' % jupyterhub.version_info[:2]
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = jupyterhub.__version__
|
||||
|
||||
language = "en"
|
||||
exclude_patterns = []
|
||||
pygments_style = 'sphinx'
|
||||
todo_include_todos = False
|
||||
|
||||
# Set the default role so we can use `foo` instead of ``foo``
|
||||
default_role = 'literal'
|
||||
|
||||
from contextlib import redirect_stdout
|
||||
from io import StringIO
|
||||
import subprocess
|
||||
|
||||
from docutils import nodes
|
||||
from sphinx.directives.other import SphinxDirective
|
||||
|
||||
# -- Config -------------------------------------------------------------
|
||||
import jupyterhub
|
||||
from jupyterhub.app import JupyterHub
|
||||
|
||||
# create a temp instance of JupyterHub just to get the output of the generate-config
|
||||
# and help --all commands.
|
||||
# -- Project information -----------------------------------------------------
|
||||
# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||||
#
|
||||
project = "JupyterHub"
|
||||
author = "Project Jupyter Contributors"
|
||||
copyright = f"{datetime.date.today().year}, {author}"
|
||||
version = "%i.%i" % jupyterhub.version_info[:2]
|
||||
release = jupyterhub.__version__
|
||||
|
||||
|
||||
# -- General Sphinx configuration --------------------------------------------
|
||||
# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
||||
#
|
||||
extensions = [
|
||||
"sphinx.ext.autodoc",
|
||||
"sphinx.ext.intersphinx",
|
||||
"sphinx.ext.napoleon",
|
||||
"autodoc_traits",
|
||||
"sphinx_copybutton",
|
||||
"sphinx-jsonschema",
|
||||
"myst_parser",
|
||||
]
|
||||
root_doc = "index"
|
||||
source_suffix = [".md", ".rst"]
|
||||
# default_role let's use use `foo` instead of ``foo`` in rST
|
||||
default_role = "literal"
|
||||
|
||||
|
||||
# -- MyST configuration ------------------------------------------------------
|
||||
# ref: https://myst-parser.readthedocs.io/en/latest/configuration.html
|
||||
#
|
||||
myst_heading_anchors = 2
|
||||
myst_enable_extensions = [
|
||||
"colon_fence",
|
||||
"deflist",
|
||||
]
|
||||
|
||||
|
||||
# -- Custom directives to generate documentation -----------------------------
|
||||
# ref: https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html
|
||||
#
|
||||
# We define custom directives to help us generate documentation using Python on
|
||||
# demand when referenced from our documentation files.
|
||||
#
|
||||
|
||||
# Create a temp instance of JupyterHub for use by two separate directive classes
|
||||
# to get the output from using the "--generate-config" and "--help-all" CLI
|
||||
# flags respectively.
|
||||
#
|
||||
jupyterhub_app = JupyterHub()
|
||||
|
||||
|
||||
@@ -70,8 +79,8 @@ class ConfigDirective(SphinxDirective):
|
||||
# The generated configuration file for this version
|
||||
generated_config = jupyterhub_app.generate_config_file()
|
||||
# post-process output
|
||||
home_dir = os.environ['HOME']
|
||||
generated_config = generated_config.replace(home_dir, '$HOME', 1)
|
||||
home_dir = os.environ["HOME"]
|
||||
generated_config = generated_config.replace(home_dir, "$HOME", 1)
|
||||
par = nodes.literal_block(text=generated_config)
|
||||
return [par]
|
||||
|
||||
@@ -87,36 +96,55 @@ class HelpAllDirective(SphinxDirective):
|
||||
|
||||
def run(self):
|
||||
# The output of the help command for this version
|
||||
buffer = StringIO()
|
||||
with redirect_stdout(buffer):
|
||||
jupyterhub_app.print_help('--help-all')
|
||||
buffer = io.StringIO()
|
||||
with contextlib.redirect_stdout(buffer):
|
||||
jupyterhub_app.print_help("--help-all")
|
||||
all_help = buffer.getvalue()
|
||||
# post-process output
|
||||
home_dir = os.environ['HOME']
|
||||
all_help = all_help.replace(home_dir, '$HOME', 1)
|
||||
home_dir = os.environ["HOME"]
|
||||
all_help = all_help.replace(home_dir, "$HOME", 1)
|
||||
par = nodes.literal_block(text=all_help)
|
||||
return [par]
|
||||
|
||||
|
||||
def setup(app):
|
||||
app.add_css_file('custom.css')
|
||||
app.add_directive('jupyterhub-generate-config', ConfigDirective)
|
||||
app.add_directive('jupyterhub-help-all', HelpAllDirective)
|
||||
app.add_css_file("custom.css")
|
||||
app.add_directive("jupyterhub-generate-config", ConfigDirective)
|
||||
app.add_directive("jupyterhub-help-all", HelpAllDirective)
|
||||
|
||||
|
||||
source_suffix = ['.rst', '.md']
|
||||
# -- Read The Docs -----------------------------------------------------------
|
||||
#
|
||||
# Since RTD runs sphinx-build directly without running "make html", we run the
|
||||
# pre-requisite steps for "make html" from here if needed.
|
||||
#
|
||||
if os.environ.get("READTHEDOCS"):
|
||||
docs = os.path.dirname(os.path.dirname(__file__))
|
||||
subprocess.check_call(["make", "metrics", "scopes"], cwd=docs)
|
||||
|
||||
# -- Options for HTML output ----------------------------------------------
|
||||
|
||||
# The theme to use for HTML
|
||||
html_theme = 'pydata_sphinx_theme'
|
||||
# -- Spell checking ----------------------------------------------------------
|
||||
# ref: https://sphinxcontrib-spelling.readthedocs.io/en/latest/customize.html#configuration-options
|
||||
#
|
||||
# The "sphinxcontrib.spelling" extension is optionally enabled if its available.
|
||||
#
|
||||
try:
|
||||
import sphinxcontrib.spelling # noqa
|
||||
except ImportError:
|
||||
pass
|
||||
else:
|
||||
extensions.append("sphinxcontrib.spelling")
|
||||
spelling_word_list_filename = "spelling_wordlist.txt"
|
||||
|
||||
html_logo = '_static/images/logo/logo.png'
|
||||
html_favicon = '_static/images/logo/favicon.ico'
|
||||
|
||||
# Paths that contain custom static files (such as style sheets)
|
||||
html_static_path = ['_static']
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
||||
#
|
||||
html_logo = "_static/images/logo/logo.png"
|
||||
html_favicon = "_static/images/logo/favicon.ico"
|
||||
html_static_path = ["_static"]
|
||||
|
||||
html_theme = "pydata_sphinx_theme"
|
||||
html_theme_options = {
|
||||
"icon_links": [
|
||||
{
|
||||
@@ -133,40 +161,34 @@ html_theme_options = {
|
||||
"use_edit_page_button": True,
|
||||
"navbar_align": "left",
|
||||
}
|
||||
|
||||
html_context = {
|
||||
"github_user": "jupyterhub",
|
||||
"github_repo": "jupyterhub",
|
||||
"github_version": "main",
|
||||
"doc_path": "docs",
|
||||
"doc_path": "docs/source",
|
||||
}
|
||||
|
||||
# -- Intersphinx ----------------------------------------------------------
|
||||
|
||||
# -- Options for linkcheck builder -------------------------------------------
|
||||
# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
|
||||
#
|
||||
linkcheck_ignore = [
|
||||
r"(.*)github\.com(.*)#", # javascript based anchors
|
||||
r"(.*)/#%21(.*)/(.*)", # /#!forum/jupyter - encoded anchor edge case
|
||||
r"https://github.com/[^/]*$", # too many github usernames / searches in changelog
|
||||
"https://github.com/jupyterhub/jupyterhub/pull/", # too many PRs in changelog
|
||||
"https://github.com/jupyterhub/jupyterhub/compare/", # too many comparisons in changelog
|
||||
]
|
||||
linkcheck_anchors_ignore = [
|
||||
"/#!",
|
||||
"/#%21",
|
||||
]
|
||||
|
||||
|
||||
# -- Intersphinx -------------------------------------------------------------
|
||||
# ref: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
|
||||
#
|
||||
intersphinx_mapping = {
|
||||
'python': ('https://docs.python.org/3/', None),
|
||||
'tornado': ('https://www.tornadoweb.org/en/stable/', None),
|
||||
"python": ("https://docs.python.org/3/", None),
|
||||
"tornado": ("https://www.tornadoweb.org/en/stable/", None),
|
||||
}
|
||||
|
||||
# -- Read The Docs --------------------------------------------------------
|
||||
|
||||
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
|
||||
if on_rtd:
|
||||
# readthedocs.org uses their theme by default, so no need to specify it
|
||||
# build both metrics and rest-api, since RTD doesn't run make
|
||||
from os.path import dirname
|
||||
from subprocess import check_call as sh
|
||||
|
||||
docs = dirname(dirname(__file__))
|
||||
sh(['make', 'metrics', 'scopes'], cwd=docs)
|
||||
|
||||
# -- Spell checking -------------------------------------------------------
|
||||
|
||||
try:
|
||||
import sphinxcontrib.spelling # noqa
|
||||
except ImportError:
|
||||
pass
|
||||
else:
|
||||
extensions.append("sphinxcontrib.spelling")
|
||||
|
||||
spelling_word_list_filename = 'spelling_wordlist.txt'
|
||||
|
||||
Reference in New Issue
Block a user