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/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/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/conf.py b/docs/conf.py deleted file mode 100644 index 4ff5430f..00000000 --- a/docs/conf.py +++ /dev/null @@ -1,88 +0,0 @@ -# Configuration file for Sphinx to build our documentation to HTML. -# -# Configuration reference: https://www.sphinx-doc.org/en/master/usage/configuration.html -# - - -# -- Project specific imports ------------------------------------------------ - -import datetime - - -# -- 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. -# -# 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", -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -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 - - -# -- 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 -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_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_static_path = ["_static"] - - -# -- Options for intersphinx extension --------------------------------------- - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} - - -# -- Options for todo extension ---------------------------------------------- - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True 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/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/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/CHANGELOG.md b/docs/source/changelog.md similarity index 96% rename from CHANGELOG.md rename to docs/source/changelog.md index 974b21ca..396b178d 100644 --- a/CHANGELOG.md +++ b/docs/source/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)) diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..744b8fc3 --- /dev/null +++ b/docs/source/conf.py @@ -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", +} 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 94% rename from docs/index.rst rename to docs/source/index.rst index 2397bb7e..b180a605 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 @@ -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 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