diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..66af176525 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,17 @@ +# Configuration on how ReadTheDocs (RTD) builds our documentation +# ref: https://readthedocs.org/projects/zero-to-jupyterhub/ +# ref: https://docs.readthedocs.io/en/stable/config-file/v2.html +# +version: 2 + +sphinx: + configuration: docs/source/conf.py + +build: + os: ubuntu-22.04 + tools: + python: "3.10" + +python: + install: + - requirements: docs/requirements.txt diff --git a/.readthedocs.yml b/.readthedocs.yml deleted file mode 100644 index 12eca699cc..0000000000 --- a/.readthedocs.yml +++ /dev/null @@ -1,25 +0,0 @@ -# Configuration on how ReadTheDocs (RTD) builds our documentation -# ref: https://readthedocs.org/projects/zero-to-jupyterhub/ -# ref: https://docs.readthedocs.io/en/stable/config-file/v2.html - -# Required (RTD configuration version) -version: 2 - -# Build documentation in the docs/ directory with Sphinx -sphinx: - configuration: docs/source/conf.py - -# Optionally build your docs in additional formats such as PDF and ePub -formats: [] - -# Optionally set the version of Python and requirements required to build your docs -python: - version: 3.7 - install: - # WARNING: This requirements file will be installed without the pip - # --upgrade flag in an existing environment. This means that if a - # package is specified without a lower boundary, we may end up - # accepting the existing version. - # - # ref: https://github.com/readthedocs/readthedocs.org/blob/0e3df509e7810e46603be47d268273c596e68455/readthedocs/doc_builder/python_environments.py#L335-L344 - - requirements: docs/requirements.txt diff --git a/docs/requirements.txt b/docs/requirements.txt index 82adf09e9b..fa53c111a6 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,12 +1,3 @@ -# The ordering of these requirements can matter. It matters if we install them -# in an environment where a dependency to them (such as sphinx) is -# pre-installed, such as it can be on RTD. For example, if a top-ordered package -# declares it needs sphinx>=1 and then a later package declares it needs -# sphinx<4 - the latter may be ignored. -# -# As long as we have myst-parser ordered before other sphinx depending packages, -# we should be good. -# chartpress myst-parser pydata-sphinx-theme diff --git a/docs/source/conf.py b/docs/source/conf.py index 3da048b539..1e4caa690d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -2,20 +2,6 @@ # # Configuration reference: https://www.sphinx-doc.org/en/master/usage/configuration.html # - -# -- Path setup -------------------------------------------------------------- - -# 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. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- Project specific imports ------------------------------------------------ - import datetime import os import re @@ -23,17 +9,39 @@ import yaml -# -- Sphinx setup function --------------------------------------------------- -# ref: https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events +# -- Project information ----------------------------------------------------- +# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information +# +project = "Zero to JupyterHub with Kubernetes" +copyright = f"{datetime.date.today().year}, Project Jupyter Contributors" +author = "Project Jupyter Contributors" -def setup(app): - app.add_css_file("custom.css") +# -- General Sphinx configuration --------------------------------------------------- +# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration +# +extensions = [ + "myst_parser", + "sphinx_copybutton", + "sphinx.ext.mathjax", + "sphinxext.opengraph", + "sphinxext.rediraffe", +] +root_doc = "index" +source_suffix = [".md"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] -# -- Referenceable variables -------------------------------------------------- +# -- General MyST configuration ----------------------------------------------------- +# ref: https://myst-parser.readthedocs.io/en/latest/configuration.html +# +myst_enable_extensions = [ + "substitution", +] +# -- Referenceable variables -------------------------------------------------- +# def _get_git_ref_from_chartpress_based_version(version): """ Get a git ref from a chartpress set version of format like @@ -72,114 +80,8 @@ def _get_git_ref_from_chartpress_based_version(version): } -# -- General MyST configuration ----------------------------------------------------- - -# myst_enable_extensions ref: https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html -myst_enable_extensions = [ - "substitution", -] - - -# -- Project information ----------------------------------------------------- -# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = "Zero to JupyterHub with Kubernetes" -copyright = f"{datetime.date.today().year}, Project Jupyter Contributors" -author = "Project Jupyter Contributors" - - -# -- General Sphinx configuration --------------------------------------------------- -# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -# Set the default role so we can use `foo` instead of ``foo`` -default_role = "literal" - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.mathjax", - "sphinx_copybutton", - "myst_parser", - "sphinxext.rediraffe", - "sphinxext.opengraph", -] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - -# The root toctree document. -root_doc = master_doc = "index" - -# The suffix(es) of source filenames. -source_suffix = [".md", ".rst"] - -# Rediraffe redirects to ensure proper redirection -rediraffe_redirects = { - "customizing/user-management": "jupyterhub/customizing/user-management", - "customizing/user-storage": "jupyterhub/customizing/user-storage", - "customizing/user-resources": "jupyterhub/customizing/user-resources", - "customizing/user-environment": "jupyterhub/customizing/user-environment", - "customizing/extending-jupyterhub": "jupyterhub/customizing/extending-jupyterhub", - "reference/glossary": "resources/glossary", - "reference/tools": "resources/tools", - "reference/reference-docs": "resources/reference-docs", - "reference/reference": "resources/reference", - "community/additional-resources": "resources/community", - "community/users-list": "resources/community", - "community/tips": "resources/community", - "setup-jupyterhub/turn-off": "jupyterhub/uninstall", - "setup-jupyterhub/setup-jupyterhub": "jupyterhub/installation", - "setup-jupyterhub/setup-helm": "kubernetes/setup-helm", - "ovh/step-zero-ovh": "kubernetes/ovh/step-zero-ovh", - "digital-ocean/step-zero-digital-ocean": "kubernetes/digital-ocean/step-zero-digital-ocean", - "ibm/step-zero-ibm": "kubernetes/ibm/step-zero-ibm", - "redhat/step-zero-openshift": "kubernetes/redhat/step-zero-openshift", - "amazon/step-zero-aws-eks": "kubernetes/amazon/step-zero-aws-eks", - "amazon/step-zero-aws": "kubernetes/amazon/step-zero-aws", - "microsoft/step-zero-azure-autoscale": "kubernetes/microsoft/step-zero-azure", - "microsoft/step-zero-azure": "kubernetes/microsoft/step-zero-azure", - "google/step-zero-gcp": "kubernetes/google/step-zero-gcp", - "create-k8s-cluster": "kubernetes/setup-kubernetes", - "turn-off": "jupyterhub/uninstall", - "setup-jupyterhub": "jupyterhub/index", - "setup-helm": "kubernetes/setup-helm", - "index-setup-jupyterhub": "jupyterhub/index", - "tools": "reference/tools", - "reference-docs": "reference/reference-docs", - "index-reference": "resources/reference", - "glossary": "reference/glossary", - "user-storage": "customizing/user-storage", - "user-resources": "customizing/user-resources", - "user-management": "customizing/user-management", - "user-environment": "customizing/user-environment", - "index-customization-guide": "jupyterhub/customization", - "extending-jupyterhub": "customizing/extending-jupyterhub", - "users-list": "community/users-list", - "tips": "community/tips", - "index-community-resources": "resources/community", - "additional-resources": "resources/community", - "upgrading": "administrator/upgrading/index", - "troubleshooting": "administrator/troubleshooting", - "security": "administrator/security", - "optimization": "administrator/optimization", - "index-administrator-guide": "administrator/index", - "debug": "administrator/debug", - "cost": "administrator/cost", - "authentication": "administrator/authentication", - "architecture": "administrator/architecture", - "advanced": "administrator/advanced", -} - -# opengraph configuration -# ogp_site_url/prefix is set automatically by RTD -ogp_image = "_static/logo.png" -ogp_use_first_image = True - # -- Generate the Helm chart configuration reference from a schema file ------ - +# # header with open("resources/reference.txt") as f: header_md = f.readlines() @@ -224,8 +126,31 @@ def parse_schema(d, md=[], depth=0, pre=""): f.write("\n".join(reference_md)) +# -- 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_css_files = ["custom.css"] + +# pydata_sphinx_theme reference: https://pydata-sphinx-theme.readthedocs.io/en/latest/ +html_theme = "pydata_sphinx_theme" +html_theme_options = { + "github_url": "https://github.com/jupyterhub/zero-to-jupyterhub-k8s/", + "use_edit_page_button": True, +} +html_context = { + "github_user": "jupyterhub", + "github_repo": "zero-to-jupyterhub-k8s", + "github_version": "main", + "doc_path": "docs/source", +} + + # -- 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 @@ -246,29 +171,77 @@ def parse_schema(d, md=[], depth=0, pre=""): ] -# -- Options for HTML output ------------------------------------------------- -# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. +# -- Options for the opengraph extension ------------------------------------- +# ref: https://github.com/wpilibsuite/sphinxext-opengraph#options # +# This extension help others provide better thumbnails and link descriptions +# when they link to this documentation from other websites, such as +# https://discourse.jupyter.org. +# +# ogp_site_url is set automatically by RTD +ogp_image = "_static/logo.png" +ogp_use_first_image = True -html_theme = "pydata_sphinx_theme" -html_theme_options = { - "github_url": "https://github.com/jupyterhub/zero-to-jupyterhub-k8s/", - "use_edit_page_button": True, -} -html_context = { - "github_user": "jupyterhub", - "github_repo": "zero-to-jupyterhub-k8s", - "github_version": "main", - "doc_path": "docs/source", -} - -html_favicon = "_static/images/logo/favicon.ico" -html_logo = "_static/images/logo/logo.png" -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] +# -- Options for the rediraffe extension ------------------------------------- +# ref: https://github.com/wpilibsuite/sphinxext-rediraffe#readme +# +# This extensions help us relocated content without breaking links. If a +# document is moved internally, we should configure a redirect like below. +# +rediraffe_branch = "main" +rediraffe_redirects = { + "customizing/user-management": "jupyterhub/customizing/user-management", + "customizing/user-storage": "jupyterhub/customizing/user-storage", + "customizing/user-resources": "jupyterhub/customizing/user-resources", + "customizing/user-environment": "jupyterhub/customizing/user-environment", + "customizing/extending-jupyterhub": "jupyterhub/customizing/extending-jupyterhub", + "reference/glossary": "resources/glossary", + "reference/tools": "resources/tools", + "reference/reference-docs": "resources/reference-docs", + "reference/reference": "resources/reference", + "community/additional-resources": "resources/community", + "community/users-list": "resources/community", + "community/tips": "resources/community", + "setup-jupyterhub/turn-off": "jupyterhub/uninstall", + "setup-jupyterhub/setup-jupyterhub": "jupyterhub/installation", + "setup-jupyterhub/setup-helm": "kubernetes/setup-helm", + "ovh/step-zero-ovh": "kubernetes/ovh/step-zero-ovh", + "digital-ocean/step-zero-digital-ocean": "kubernetes/digital-ocean/step-zero-digital-ocean", + "ibm/step-zero-ibm": "kubernetes/ibm/step-zero-ibm", + "redhat/step-zero-openshift": "kubernetes/redhat/step-zero-openshift", + "amazon/step-zero-aws-eks": "kubernetes/amazon/step-zero-aws-eks", + "amazon/step-zero-aws": "kubernetes/amazon/step-zero-aws", + "microsoft/step-zero-azure-autoscale": "kubernetes/microsoft/step-zero-azure", + "microsoft/step-zero-azure": "kubernetes/microsoft/step-zero-azure", + "google/step-zero-gcp": "kubernetes/google/step-zero-gcp", + "create-k8s-cluster": "kubernetes/setup-kubernetes", + "turn-off": "jupyterhub/uninstall", + "setup-jupyterhub": "jupyterhub/index", + "setup-helm": "kubernetes/setup-helm", + "index-setup-jupyterhub": "jupyterhub/index", + "tools": "reference/tools", + "reference-docs": "reference/reference-docs", + "index-reference": "resources/reference", + "glossary": "reference/glossary", + "user-storage": "customizing/user-storage", + "user-resources": "customizing/user-resources", + "user-management": "customizing/user-management", + "user-environment": "customizing/user-environment", + "index-customization-guide": "jupyterhub/customization", + "extending-jupyterhub": "customizing/extending-jupyterhub", + "users-list": "community/users-list", + "tips": "community/tips", + "index-community-resources": "resources/community", + "additional-resources": "resources/community", + "upgrading": "administrator/upgrading/index", + "troubleshooting": "administrator/troubleshooting", + "security": "administrator/security", + "optimization": "administrator/optimization", + "index-administrator-guide": "administrator/index", + "debug": "administrator/debug", + "cost": "administrator/cost", + "authentication": "administrator/authentication", + "architecture": "administrator/architecture", + "advanced": "administrator/advanced", +}