Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update of readthedocs config and docs/source/conf.py #2909

Merged
merged 3 commits into from Nov 1, 2022
Merged

docs: update of readthedocs config and docs/source/conf.py #2909

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
52044de
docs: update readthedocs config to ubuntu build
consideRatio Oct 22, 2022
7c24a47
docs: update conf.py like repo2docker and binderhub was
consideRatio Oct 22, 2022
b0afac9
Apply suggestions from code review
consideRatio Oct 25, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
17 changes: 17 additions & 0 deletions .readthedocs.yaml
View file
Open in desktop
@@ -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
25 changes: 0 additions & 25 deletions .readthedocs.yml
View file
Open in desktop

This file was deleted.

9 changes: 0 additions & 9 deletions docs/requirements.txt
View file
Open in desktop
@@ -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
Expand Down
272 changes: 123 additions & 149 deletions docs/source/conf.py
View file
Open in desktop
Expand Up @@ -2,38 +2,46 @@
#
# 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
import subprocess

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
Expand Down Expand Up @@ -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"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the impact of removing default_role?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its purpose is for rST docs i think, so none in this project without rST.

Goal: reduced complexity.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Example

With default_role as literal in rST, you can write `test` to have it in code style
Without default_role as literal in rST, you must write ``test`` to have it in code style


# 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()
Expand Down Expand Up @@ -224,8 +126,32 @@ 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,
"twitter_url": "https://twitter.com/mybinderteam",
consideRatio marked this conversation as resolved.
Show resolved Hide resolved
}
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
Expand All @@ -246,29 +172,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",
}