Merge pull request #8 from consideRatio/pr/update-docs

docs: use jupyterhub_sphinx_theme, add make devenv/linkcheck

docs/Makefile

@@ -1,5 +1,7 @@
 # Minimal makefile for Sphinx documentation
 #
+# Use this file on linux/mac computers by running `make devenv` for example.
+#
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
@@ -18,3 +20,21 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Manually added commands
+# ----------------------------------------------------------------------------
+
+# For local development:
+# - builds and rebuilds html on changes to source
+# - starts a livereload enabled webserver and opens up a browser
+# 
+devenv:
+	sphinx-autobuild -b html --open-browser "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
+
+# For local development and CI:
+# - verifies that links are valid
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS)
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."

docs/make.bat

@@ -2,34 +2,56 @@
 
 pushd %~dp0
 
-REM Command file for Sphinx documentation
+REM Minimal command file for Sphinx documentation
+
+REM Use this file on windows computers by running `make.bat devenv` for example.
 
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=source
 set BUILDDIR=_build
 
+if "%1" == "" goto help
+if "%1" == "devenv" goto devenv
+if "%1" == "linkcheck" goto linkcheck
+goto default
+
+
+:default
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
+	echo.The 'sphinx-build' command was not found. Open and read README.md!
+	exit /b 1
+)
+%SPHINXBUILD% -M %1 "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS%
+goto end
+
+
+:help
+%SPHINXBUILD% -M help "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS%
+goto end
+
+
+:devenv
+sphinx-autobuild >NUL 2>NUL
+if errorlevel 9009 (
 	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.https://www.sphinx-doc.org/
+	echo.The 'sphinx-autobuild' command was not found. Open and read README.md!
 	exit /b 1
 )
+sphinx-autobuild -b html --open-browser "%SOURCEDIR%" "%BUILDDIR%/html" %SPHINXOPTS%
+goto end
 
-if "%1" == "" goto help
 
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+:linkcheck
+%SPHINXBUILD% -b linkcheck "%SOURCEDIR%" "%BUILDDIR%/linkcheck" %SPHINXOPTS%
+echo.
+echo.Link check complete; look for any errors in the above output
+echo.or in "%BUILDDIR%/linkcheck/output.txt".
 goto end
 
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :end
 popd

docs/requirements.txt

@@ -6,8 +6,15 @@
 #
 --editable .
 
+# autodoc-traits provides sphinx directives to create reference documentation
+# about our traitlet configurable Python classes.
 autodoc-traits
-myst-parser
-pydata-sphinx-theme
-sphinx
-sphinx-copybutton
+
+# jupyterhub-sphinx-theme is based on pydata-sphinx-theme and itself require
+# that theme, myst-parser, sphinx-copybutton, sphinx-opengraph:
+# https://github.com/jupyterhub/jupyterhub-sphinx-theme/blob/d4071da94ccb40216389c413c04a0bd684dc764d/pyproject.toml#L16-L21
+#
+jupyterhub-sphinx-theme
+
+sphinx-autobuild
+sphinxext-rediraffe

docs/source/changelog.md

@@ -16,4 +16,4 @@ command line for details.
 
 ### 1.0.0 - 2022-12-06
 
-([full changelog](https://github.com/jupyterhub/jupyterhub-python-repo-template/compare/1.0.0...1.0.1))
+([full changelog](https://github.com/jupyterhub/jupyterhub-python-repo-template/compare/0.1.0...1.0.0))

docs/source/conf.py

@@ -1,78 +1,48 @@
 # ----------------------------------------------------------------------------
-#  --- MUST ADAPT THIS FILE FOR YOUR PROJECT ---
+# --- MUST ADAPT THIS FILE FOR YOUR PROJECT ---
 # --- Instructions below ---
 #
 # * Search and replace `jupyterhub-python-repo-template` with the name of your
 #   repository
-# * Search after the `TODO` keyword and follow the instructions in the comment
 # ----------------------------------------------------------------------------
 
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# 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.
+# Configuration file for Sphinx to build our documentation to HTML.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-# -- Project specific imports ------------------------------------------------
-
 import datetime
 
 # -- Project information -----------------------------------------------------
-
+# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+#
 project = "jupyterhub-python-repo-template"
 copyright = f"{datetime.date.today().year}, Project Jupyter Contributors"
 author = "Project Jupyter Contributors"
 
 
-# -- General configuration ---------------------------------------------------
+# -- 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.
-# TODO add more extensions based on needs here
+#
 extensions = [
+    # jupyterhub_sphinx_theme activates the sphinx-copybutton and
+    # sphinx-opengraph extensions as well.
+    "jupyterhub_sphinx_theme",
     "autodoc_traits",
-    "sphinx_copybutton",
     "myst_parser",
+    "sphinxext.rediraffe",
 ]
+root_doc = "index"
+source_suffix = [".md"]
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-# 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 = ["_build", "Thumbs.db", ".DS_Store"]
-
-# The root toctree document.
-root_doc = master_doc = "index"
+# default_role is set for use with reStructuredText that we still need to use in
+# docstrings in the autodoc_traits inspected Python module. It makes single
+# backticks around text, like `my_function`, behave as in typical Markdown.
+default_role = "literal"
 
-# The suffix(es) of source filenames.
-source_suffix = [".md"]
 
 # -- 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.
 #
-
-# TODO: Consider updating the following section with the desired html theme if needed
-html_theme = "pydata_sphinx_theme"
+html_theme = "jupyterhub_sphinx_theme"
 html_theme_options = {
     "github_url": "https://github.com/jupyterhub/jupyterhub-python-repo-template/",
     "use_edit_page_button": True,
@@ -84,20 +54,56 @@
     "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".
+# 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"]
 
+# About html_logo and html_favicon configuration:
+#
+# jupyterhub_sphinx_theme provides a jupyterhub favicon (html_favicon) and logo
+# by default, where the logo is provided for light/dark respectively not under
+# html_logo but under html_theme_options.logo.[image_light|image_dark] which
+# will take precedence over html_logo configuration.
+#
+# ref: https://github.com/pydata/pydata-sphinx-theme/blob/v0.12.0/docs/user_guide/branding.rst
+# ref: https://github.com/choldgraf/jupyterhub-sphinx-theme/blob/f97104c11cae55869ddc8394eb83594bd5c7d075/src/jupyterhub_sphinx_theme/__init__.py#L17-L54
+#
+
+
 # -- 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-python-repo-template/pull/",  # too many PRs in changelog
+    "https://github.com/jupyterhub/jupyterhub-python-repo-template/compare/",  # too many comparisons in changelog
+    r"https?://(localhost|127.0.0.1).*",  # ignore localhost references in auto-links
+]
+linkcheck_anchors_ignore = [
+    "/#!",
+    "/#%21",
+]
+
+
+# -- Options for the opengraph extension -------------------------------------
+# ref: https://github.com/wpilibsuite/sphinxext-opengraph#options
+#
+# ogp_site_url is set automatically by jupyterhub-sphinx-theme
+ogp_image = "_static/logo.png"
+ogp_use_first_image = True
 
-# A list of regular expressions that match anchors Sphinx should skip when checking
-# the validity of anchors in links.
 
-# TODO: Consider adding links that are known to fail from time to time to the list below
-#       so that they are skipped from validation
-linkcheck_ignore = []
+# -- 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, a redirect like should be configured below to
+# help us not break links.
+#
+rediraffe_branch = "main"
+rediraffe_redirects = {
+    # "old-file": "new-folder/new-file-name",
+}

docs/source/docs.md

@@ -2,8 +2,8 @@
 
 # Documentation
 
-This section contains information about documentation practices and standards
-that are usually used across JupyterHub project repositories.
+This section contains information about practices and standards that are usually used
+across JupyterHub project repositories.
 
 ## The recommended `docs` directory structure
 
@@ -14,10 +14,6 @@ The `docs` directory usually has the overall structure described below.
 📦docs
  ┣ 📂source
  ┃ ┣ 📂_static
- ┃ ┃ ┗ 📂images
- ┃ ┃ ┃ ┗ 📂logo
- ┃ ┃ ┃ ┃ ┣ 📜favicon.ico
- ┃ ┃ ┃ ┃ ┗ 📜logo.png
  ┃ ┣ 📜changelog.md
  ┃ ┣ 📜conf.py
  ┃ ┗ 📜index.md
@@ -73,7 +69,11 @@ However, consider changing it in the following cases:
 1. Build the docs locally by running
 
    ```bash
+   # single build
    make html
+
+   # rebuild and refresh the browser on changes
+   make devenv
    ```
 
 1. Checkout the rendered html assets built by the `make` command in the newly generated `docs/_build` directory