From 693c9613ac9c07ea3d998ac54e78454d832c5c17 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Fri, 4 Nov 2022 13:13:35 +0100 Subject: [PATCH 1/4] docs: relocate source files from docs to docs/source --- .readthedocs.yaml | 6 +++--- README.md | 2 +- docs/Makefile | 2 +- docs/convenience/packages/theia.rst | 1 - docs/make.bat | 2 +- .../_static}/images/labextension-launcher.png | Bin docs/{ => source}/_static/images/logo/favicon.ico | Bin .../_static}/images/nbextension-tree.png | Bin docs/{ => source}/arbitrary-ports-hosts.rst | 0 docs/{ => source}/conf.py | 11 ++++------- docs/{ => source}/contributing/release.rst | 0 docs/{ => source}/convenience/new.rst | 0 docs/source/convenience/packages/theia.rst | 1 + docs/{ => source}/examples.rst | 0 docs/{ => source}/index.rst | 2 +- docs/{ => source}/install.rst | 0 docs/{ => source}/launchers.rst | 4 ++-- docs/{ => source}/server-process.rst | 0 18 files changed, 14 insertions(+), 17 deletions(-) delete mode 120000 docs/convenience/packages/theia.rst rename docs/{ => source/_static}/images/labextension-launcher.png (100%) rename docs/{ => source}/_static/images/logo/favicon.ico (100%) rename docs/{ => source/_static}/images/nbextension-tree.png (100%) rename docs/{ => source}/arbitrary-ports-hosts.rst (100%) rename docs/{ => source}/conf.py (92%) rename docs/{ => source}/contributing/release.rst (100%) rename docs/{ => source}/convenience/new.rst (100%) create mode 120000 docs/source/convenience/packages/theia.rst rename docs/{ => source}/examples.rst (100%) rename docs/{ => source}/index.rst (98%) rename docs/{ => source}/install.rst (100%) rename docs/{ => source}/launchers.rst (90%) rename docs/{ => source}/server-process.rst (100%) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 70f903af..6bf99912 100644 --- a/.readthedocs.yaml +++ b/.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 diff --git a/README.md b/README.md index e07e0f70..0fde5a52 100644 --- a/README.md +++ b/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. diff --git a/docs/Makefile b/docs/Makefile index 5fd9d877..9d722500 100644 --- a/docs/Makefile +++ b/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". diff --git a/docs/convenience/packages/theia.rst b/docs/convenience/packages/theia.rst deleted file mode 120000 index bbfbf844..00000000 --- a/docs/convenience/packages/theia.rst +++ /dev/null @@ -1 +0,0 @@ -../../../contrib/theia/README.rst \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat index ba30c170..49506420 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -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 diff --git a/docs/images/labextension-launcher.png b/docs/source/_static/images/labextension-launcher.png similarity index 100% rename from docs/images/labextension-launcher.png rename to docs/source/_static/images/labextension-launcher.png diff --git a/docs/_static/images/logo/favicon.ico b/docs/source/_static/images/logo/favicon.ico similarity index 100% rename from docs/_static/images/logo/favicon.ico rename to docs/source/_static/images/logo/favicon.ico diff --git a/docs/images/nbextension-tree.png b/docs/source/_static/images/nbextension-tree.png similarity index 100% rename from docs/images/nbextension-tree.png rename to docs/source/_static/images/nbextension-tree.png diff --git a/docs/arbitrary-ports-hosts.rst b/docs/source/arbitrary-ports-hosts.rst similarity index 100% rename from docs/arbitrary-ports-hosts.rst rename to docs/source/arbitrary-ports-hosts.rst diff --git a/docs/conf.py b/docs/source/conf.py similarity index 92% rename from docs/conf.py rename to docs/source/conf.py index 4ff5430f..89eb372f 100644 --- a/docs/conf.py +++ b/docs/source/conf.py @@ -53,18 +53,15 @@ # -- Options for HTML output ------------------------------------------------- # ref: http://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -# FIXME: change to pydata_sphinx_theme +# FIXME: change to sphinx_book_theme or pydata_sphinx_theme +# +# Alabaster theme options: https://alabaster.readthedocs.io/en/latest/customization.html#theme-options html_theme = "alabaster" html_theme_options = { - "github_url": "https://github.com/jupyterhub/jupyter-server-proxy/", - "use_edit_page_button": True, -} -html_context = { "github_user": "jupyterhub", "github_repo": "jupyter-server-proxy", - "github_version": "main", - "doc_path": "docs", } +html_context = {} html_favicon = "_static/images/logo/favicon.ico" # FIXME: Add project logo diff --git a/docs/contributing/release.rst b/docs/source/contributing/release.rst similarity index 100% rename from docs/contributing/release.rst rename to docs/source/contributing/release.rst diff --git a/docs/convenience/new.rst b/docs/source/convenience/new.rst similarity index 100% rename from docs/convenience/new.rst rename to docs/source/convenience/new.rst diff --git a/docs/source/convenience/packages/theia.rst b/docs/source/convenience/packages/theia.rst new file mode 120000 index 00000000..49076d4b --- /dev/null +++ b/docs/source/convenience/packages/theia.rst @@ -0,0 +1 @@ +../../../../contrib/theia/README.rst \ No newline at end of file diff --git a/docs/examples.rst b/docs/source/examples.rst similarity index 100% rename from docs/examples.rst rename to docs/source/examples.rst diff --git a/docs/index.rst b/docs/source/index.rst similarity index 98% rename from docs/index.rst rename to docs/source/index.rst index 2397bb7e..1a884d47 100644 --- a/docs/index.rst +++ b/docs/source/index.rst @@ -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 `_ for - `dask `_. + `dask `_. Contents diff --git a/docs/install.rst b/docs/source/install.rst similarity index 100% rename from docs/install.rst rename to docs/source/install.rst diff --git a/docs/launchers.rst b/docs/source/launchers.rst similarity index 90% rename from docs/launchers.rst rename to docs/source/launchers.rst index 7897fd13..c26340a9 100644 --- a/docs/launchers.rst +++ b/docs/source/launchers.rst @@ -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. diff --git a/docs/server-process.rst b/docs/source/server-process.rst similarity index 100% rename from docs/server-process.rst rename to docs/source/server-process.rst From 41ac753dc063b9af6966659f52440bc482c2dc45 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Fri, 4 Nov 2022 13:30:42 +0100 Subject: [PATCH 2/4] docs: switch to sphinx-book-theme and refresh sphinx conf.py --- docs/requirements.txt | 4 +- docs/source/conf.py | 112 +++++++++++++++++++++--------------------- 2 files changed, 60 insertions(+), 56 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index ec2e63ed..63f4be10 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,6 @@ myst-parser -pydata-sphinx-theme sphinx-autobuild +sphinx-book-theme sphinx-copybutton +sphinxext-opengraph +sphinxext-rediraffe diff --git a/docs/source/conf.py b/docs/source/conf.py index 89eb372f..744b8fc3 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -2,84 +2,86 @@ # # Configuration reference: https://www.sphinx-doc.org/en/master/usage/configuration.html # - - -# -- Project specific imports ------------------------------------------------ - 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 configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. +# -- 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. # -# needs_sphinx = '1.0' - -# 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.intersphinx', - 'sphinx.ext.todo', - "sphinx_copybutton", "myst_parser", + "sphinx_copybutton", + "sphinxext.opengraph", + "sphinxext.rediraffe", ] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. +root_doc = "index" source_suffix = [".md", ".rst"] - -# The root toctree document. -root_doc = master_doc = 'index' - -# 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 = [u'_build', 'Thumbs.db', '.DS_Store'] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = None +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # -- Options for HTML output ------------------------------------------------- -# ref: http://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -# FIXME: change to sphinx_book_theme or pydata_sphinx_theme +# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output # -# Alabaster theme options: https://alabaster.readthedocs.io/en/latest/customization.html#theme-options -html_theme = "alabaster" -html_theme_options = { - "github_user": "jupyterhub", - "github_repo": "jupyter-server-proxy", -} -html_context = {} - -html_favicon = "_static/images/logo/favicon.ico" -# FIXME: Add project logo # 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_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 intersphinx extension --------------------------------------- +# -- 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", +] -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} +# -- 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 todo extension ---------------------------------------------- -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = 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", +} From a2be330ed12606e49d6beabedf34d541da1e0c65 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Fri, 4 Nov 2022 13:31:04 +0100 Subject: [PATCH 3/4] docs: fix heading levels and details in changelog --- CHANGELOG.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 974b21ca..396b178d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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)) From e6ec041dda7c88991b7ec6ebb44a4ae1e7e44163 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Fri, 4 Nov 2022 13:37:51 +0100 Subject: [PATCH 4/4] docs: relocate changelog to built documentation --- RELEASE.md | 6 +++--- CHANGELOG.md => docs/source/changelog.md | 0 docs/source/index.rst | 8 ++++++++ 3 files changed, 11 insertions(+), 3 deletions(-) rename CHANGELOG.md => docs/source/changelog.md (100%) diff --git a/RELEASE.md b/RELEASE.md index b67e5f0d..2e00cbb0 100644 --- a/RELEASE.md +++ b/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 diff --git a/CHANGELOG.md b/docs/source/changelog.md similarity index 100% rename from CHANGELOG.md rename to docs/source/changelog.md diff --git a/docs/source/index.rst b/docs/source/index.rst index 1a884d47..b180a605 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -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