Merge pull request #352 from consideRatio/pr/docs-refactor

docs: switch from alabaster to sphinx-book-theme, and misc docs build system maintenance

Author: consideRatio

.readthedocs.yaml

@@ -4,6 +4,9 @@
 #
 version: 2
 
+sphinx:
+  configuration: docs/source/conf.py
+
 build:
   os: ubuntu-22.04
   tools:
@@ -12,6 +15,3 @@ build:
 python:
   install:
     - requirements: docs/requirements.txt
-
-sphinx:
-  configuration: docs/conf.py

README.md

@@ -27,7 +27,7 @@ The primary use cases are:
     JupyterLab extensions) to access web APIs of other processes running
     locally in a safe manner. This is used by the [JupyterLab
     extension](https://github.com/dask/dask-labextension) for
-    [dask](https://dask.org/).
+    [dask](https://www.dask.org/).
 
 [The documentation](https://jupyter-server-proxy.readthedocs.io/)
 contains information on installation & usage.

RELEASE.md

@@ -29,9 +29,9 @@ For you to follow along according to these instructions, you need:
    python setup.py sdist bdist_wheel
    ```
 
-2. Update [CHANGELOG.md](CHANGELOG.md). Doing this can be made easier with the
-   help of the
-   [choldgraf/github-activity](https://github.com/choldgraf/github-activity)
+2. Update [changelog.md](docs/source/changelog.md). Doing this can be made
+   easier with the help of the
+   [executablebooks/github-activity](https://github.com/executablebooks/github-activity)
    utility.
 
 ## Steps to make a release

docs/Makefile

@@ -4,7 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
+SOURCEDIR     = source
 BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".

docs/conf.py

@@ -7,7 +7,7 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set SOURCEDIR=.
+set SOURCEDIR=source
 set BUILDDIR=_build
 
 if "%1" == "" goto help

docs/convenience/packages/theia.rst

@@ -1,4 +1,6 @@
 myst-parser
-pydata-sphinx-theme
 sphinx-autobuild
+sphinx-book-theme
 sphinx-copybutton
+sphinxext-opengraph
+sphinxext-rediraffe

docs/make.bat

@@ -1,25 +1,27 @@
+# Changelog
+
 ## 3.2
 
 ### 3.2.1 - 2022-01-24
 
 3.2.1 is a security release, fixing a vulnerability [GHSA-gcv9-6737-pjqw](https://github.com/jupyterhub/jupyter-server-proxy/security/advisories/GHSA-gcv9-6737-pjqw) where `allowed_hosts` were not validated correctly.
 
-## Maintenance and upkeep improvements
+#### Maintenance and upkeep improvements
 
+- Remove empty JupyterLab style [#314](https://github.com/jupyterhub/jupyter-server-proxy/pull/314) ([@bollwyvl](https://github.com/bollwyvl))
 - Modernize docs without making changes to its content [#313](https://github.com/jupyterhub/jupyter-server-proxy/pull/313) ([@consideRatio](https://github.com/consideRatio))
 - Remove no longer needed logic involving six [#312](https://github.com/jupyterhub/jupyter-server-proxy/pull/312) ([@consideRatio](https://github.com/consideRatio))
 - Update language, from master to main [#311](https://github.com/jupyterhub/jupyter-server-proxy/pull/311) ([@consideRatio](https://github.com/consideRatio))
 
-## Other merged PRs
+#### Continuous integration improvements
 
-- Remove empty JupyterLab style [#314](https://github.com/jupyterhub/jupyter-server-proxy/pull/314) ([@bollwyvl](https://github.com/bollwyvl))
 - ci: avoid triggering ci twice on pre-commit.ci/dependabot prs [#310](https://github.com/jupyterhub/jupyter-server-proxy/pull/310) ([@consideRatio](https://github.com/consideRatio))
 
-## Contributors to this release
+#### Contributors to this release
 
 ([GitHub contributors page for this release](https://github.com/jupyterhub/jupyter-server-proxy/graphs/contributors?from=2021-11-29&to=2022-01-19&type=c))
 
-[@bollwyvl](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyter-server-proxy+involves%3Abollwyvl+updated%3A2021-11-29..2022-01-19&type=Issues) | [@consideRatio](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyter-server-proxy+involves%3AconsideRatio+updated%3A2021-11-29..2022-01-19&type=Issues) | [@welcome](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyter-server-proxy+involves%3Awelcome+updated%3A2021-11-29..2022-01-19&type=Issues) | [@yuvipanda](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyter-server-proxy+involves%3Ayuvipanda+updated%3A2021-11-29..2022-01-19&type=Issues)
+[@bollwyvl](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyter-server-proxy+involves%3Abollwyvl+updated%3A2021-11-29..2022-01-19&type=Issues) | [@consideRatio](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyter-server-proxy+involves%3AconsideRatio+updated%3A2021-11-29..2022-01-19&type=Issues) | [@yuvipanda](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyter-server-proxy+involves%3Ayuvipanda+updated%3A2021-11-29..2022-01-19&type=Issues)
 
 
 ### 3.2.0 - 2021-11-29
@@ -51,7 +53,7 @@
 
 - Fix link to contributing.md [#291](https://github.com/jupyterhub/jupyter-server-proxy/pull/291) ([@kinow](https://github.com/kinow))
 
-#### Continuous integration
+#### Continuous integration improvements
 
 - Test with lab [#298](https://github.com/jupyterhub/jupyter-server-proxy/pull/298) ([@maresb](https://github.com/maresb))
 - Open browser not required for running pytests [#273](https://github.com/jupyterhub/jupyter-server-proxy/pull/273) ([@candlerb](https://github.com/candlerb))
@@ -85,11 +87,11 @@
 
 - Reduce (and test) sdist size [#263](https://github.com/jupyterhub/jupyter-server-proxy/pull/263) ([@bollwyvl](https://github.com/bollwyvl))
 
-#### Continuous integration
+#### Continuous integration improvements
 
 - Add acceptance testing with robotframework(-jupyterlibrary) [#269](https://github.com/jupyterhub/jupyter-server-proxy/pull/269) ([@bollwyvl](https://github.com/bollwyvl))
 
-#### #### Dependency updates
+#### Dependency updates
 
 - Bump postcss from 7.0.35 to 7.0.36 in /jupyterlab-server-proxy [#277](https://github.com/jupyterhub/jupyter-server-proxy/pull/277) ([@dependabot](https://github.com/dependabot))
 - Bump normalize-url from 4.5.0 to 4.5.1 in /jupyterlab-server-proxy [#276](https://github.com/jupyterhub/jupyter-server-proxy/pull/276) ([@dependabot](https://github.com/dependabot))
@@ -143,7 +145,7 @@ version jumps from 2.1.2 to 3.0.0.
 * Breaking: Replace host_whitelist with host_allowlist [#256](https://github.com/jupyterhub/jupyter-server-proxy/pull/256) ([@manics](https://github.com/manics))
 * Switch from notebook to jupyter-server [#254](https://github.com/jupyterhub/jupyter-server-proxy/pull/254) ([@manics](https://github.com/manics))
 
-#### Continuous integration
+#### Continuous integration improvements
 
 * Move build.yaml into test.yaml [#255](https://github.com/jupyterhub/jupyter-server-proxy/pull/255) ([@manics](https://github.com/manics))
 * Fix build.yaml workflow [#249](https://github.com/jupyterhub/jupyter-server-proxy/pull/249) ([@manics](https://github.com/manics))

docs/requirements.txt

@@ -0,0 +1,87 @@
+# Configuration file for Sphinx to build our documentation to HTML.
+#
+# Configuration reference: https://www.sphinx-doc.org/en/master/usage/configuration.html
+#
+import datetime
+
+
+# -- Project information -----------------------------------------------------
+# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+#
+project = "Jupyter Server Proxy"
+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
+#
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+#
+extensions = [
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinxext.opengraph",
+    "sphinxext.rediraffe",
+]
+root_doc = "index"
+source_suffix = [".md", ".rst"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- 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"]
+
+# sphinx_book_theme reference: https://sphinx-book-theme.readthedocs.io/en/latest/?badge=latest
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "home_page_in_toc": True,
+    "repository_url": "https://github.com/jupyterhub/jupyter-server-proxy/",
+    "repository_branch": "main",
+    "path_to_docs": "docs/source",
+    "use_download_button": False,
+    "use_edit_page_button": True,
+    "use_issues_button": True,
+    "use_repository_button": True,
+}
+
+
+# -- 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/jupyter-server-proxy/pull/",  # too many PRs in changelog
+    "https://github.com/jupyterhub/jupyter-server-proxy/compare/",  # too many comparisons in changelog
+]
+linkcheck_anchors_ignore = [
+    "/#!",
+    "/#%21",
+]
+
+
+# -- Options for the opengraph extension -------------------------------------
+# ref: https://github.com/wpilibsuite/sphinxext-opengraph#options
+#
+# ogp_site_url is set automatically by RTD
+# ogp_image = "_static/images/logo/logo.png"
+ogp_use_first_image = True
+
+
+# -- 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 = {
+    # "old-file": "new-folder/new-file-name",
+}

docs/images/labextension-launcher.png renamed to docs/source/_static/images/labextension-launcher.png

@@ -0,0 +1 @@
+../../../../contrib/theia/README.rst

docs/_static/images/logo/favicon.ico renamed to docs/source/_static/images/logo/favicon.ico

@@ -21,7 +21,7 @@ The primary use cases are:
    JupyterLab extensions) to access web APIs of other processes
    running locally in a safe manner. This is used by the `JupyterLab
    extension <https://github.com/dask/dask-labextension>`_ for
-   `dask <https://dask.org/>`_.
+   `dask <https://www.dask.org/>`_.
 
 
 Contents
@@ -72,3 +72,11 @@ Contributions of all kinds - documentation, issues, blog posts, code, are most w
 
    contributing/release
    convenience/new
+
+Changelog
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   changelog

docs/images/nbextension-tree.png renamed to docs/source/_static/images/nbextension-tree.png

@@ -16,7 +16,7 @@ menu in the notebook's default tree view. Note that a new instance
 is **not** launched every time you click an item - if the process
 is already running, it is reused.
 
-.. image:: images/nbextension-tree.png
+.. image:: _static/images/nbextension-tree.png
 
 JupyterLab Launcher Extension
 =============================
@@ -31,6 +31,6 @@ to provide launcher icons for registered server processes.
 This should provide icons for each registered process in the main
 JupyterLab launcher
 
-.. image:: images/labextension-launcher.png
+.. image:: _static/images/labextension-launcher.png
 
 Clicking on them will open the application in a new window.