From edd7cdf3c67c8137df4b8e1e1df49460d3b03e0a Mon Sep 17 00:00:00 2001 From: Luong Vo Date: Mon, 10 Oct 2022 01:46:17 -0700 Subject: [PATCH 1/7] fix typo with --show-progress-page argument in example close https://github.com/jupyterhub/the-littlest-jupyterhub/issues/827 --- docs/topic/customizing-installer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topic/customizing-installer.rst b/docs/topic/customizing-installer.rst index 3699ded..e3a2b04 100644 --- a/docs/topic/customizing-installer.rst +++ b/docs/topic/customizing-installer.rst @@ -44,7 +44,7 @@ For example, to enable the progress page and add the first *admin* user, you wou curl -L https://tljh.jupyter.org/bootstrap.py \ | sudo python3 - \ - --admin admin --showprogress-page + --admin admin --show-progress-page Adding admin users =================== From 27dba29e049b8b509a41cc377ad942ab56d684b3 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 14 Nov 2022 13:26:59 +0100 Subject: [PATCH 2/7] ci: fix deprecation of set-output in github workflows The -c flag on jq was used to emit JSON on a single line instead of ending up with multi-line output, which would make it harder to pass as output to an environment variable. --- .github/workflows/integration-test.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/integration-test.yaml b/.github/workflows/integration-test.yaml index a0cf9fa..c1d8e16 100644 --- a/.github/workflows/integration-test.yaml +++ b/.github/workflows/integration-test.yaml @@ -50,9 +50,9 @@ jobs: matrix_post_filter=$( echo "$matrix_include_pre_filter" \ | yq e --output-format=json '.' - \ - | jq '{"include": map( . | select(.dont_run_on_ref != "${{ github.ref }}" ))}' + | jq -c '{"include": map( . | select(.dont_run_on_ref != "${{ github.ref }}" ))}' ) - echo ::set-output name=matrix::$(echo "$matrix_post_filter") + echo "matrix=$matrix_post_filter" >> $GITHUB_OUTPUT echo "The subsequent job's matrix are:" echo $matrix_post_filter | jq '.' From 3275fb7637dfdcc24d9633726e34a5e505dd766e Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 14 Nov 2022 14:19:33 +0100 Subject: [PATCH 3/7] ci: colorize output of jq --- .github/workflows/integration-test.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/integration-test.yaml b/.github/workflows/integration-test.yaml index c1d8e16..cee1049 100644 --- a/.github/workflows/integration-test.yaml +++ b/.github/workflows/integration-test.yaml @@ -55,7 +55,7 @@ jobs: echo "matrix=$matrix_post_filter" >> $GITHUB_OUTPUT echo "The subsequent job's matrix are:" - echo $matrix_post_filter | jq '.' + echo $matrix_post_filter | jq -C '.' env: matrix_include_pre_filter: | - name: "Int. tests: Ubuntu 18.04, Py 3.6" From 52f5f008541ea7fa004a70e8b9e2e1ca8e471798 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 28 Nov 2022 09:18:31 +0100 Subject: [PATCH 4/7] docs: relocate logo to _static for conformity --- bootstrap/bootstrap.py | 2 +- docs/{ => _static}/images/logo/favicon.ico | Bin docs/{ => _static}/images/logo/logo.png | Bin 3 files changed, 1 insertion(+), 1 deletion(-) rename docs/{ => _static}/images/logo/favicon.ico (100%) rename docs/{ => _static}/images/logo/logo.png (100%) diff --git a/bootstrap/bootstrap.py b/bootstrap/bootstrap.py index f3759b7..943fcb9 100644 --- a/bootstrap/bootstrap.py +++ b/bootstrap/bootstrap.py @@ -59,7 +59,7 @@ progress_page_html = """ - +
Please wait while your TLJH is setting up...
Click the button below to see the logs
diff --git a/docs/images/logo/favicon.ico b/docs/_static/images/logo/favicon.ico similarity index 100% rename from docs/images/logo/favicon.ico rename to docs/_static/images/logo/favicon.ico diff --git a/docs/images/logo/logo.png b/docs/_static/images/logo/logo.png similarity index 100% rename from docs/images/logo/logo.png rename to docs/_static/images/logo/logo.png From 89603d1b5c3c0b0832983ca25dac1eee988041ba Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 28 Nov 2022 09:25:14 +0100 Subject: [PATCH 5/7] docs: remove reference to not-available image --- docs/topic/jupyterhub-configurator.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/topic/jupyterhub-configurator.rst b/docs/topic/jupyterhub-configurator.rst index 6fdce76..f319573 100644 --- a/docs/topic/jupyterhub-configurator.rst +++ b/docs/topic/jupyterhub-configurator.rst @@ -6,9 +6,6 @@ JupyterHub Configurator The `JupyterHub configurator `_ allows admins to change a subset of hub settings via a GUI. -.. image:: ../images/jupyterhub-configurator.png - :alt: Changing the default JupyterHub interface - Enabling the configurator ========================= From e30a97963921deec7e812801262e68446e8eede2 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 28 Nov 2022 09:31:46 +0100 Subject: [PATCH 6/7] docs: refresh conf.py, add opengraph and rediraffe --- docs/conf.py | 128 ++++++++++++++++++++++++++++-------------- docs/requirements.txt | 8 ++- 2 files changed, 90 insertions(+), 46 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e8eec8d..321b5f2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,54 +1,96 @@ -import os +# 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 = "The Littlest JupyterHub" +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 = [ + "sphinx_copybutton", + "sphinxext.opengraph", + "sphinxext.rediraffe", +] +root_doc = "index" source_suffix = [".rst"] -project = "The Littlest JupyterHub" -copyright = "2018, JupyterHub Team" -author = "JupyterHub Team" -# The short X.Y version -version = "" -# The full version, including alpha/beta/rc tags -release = "v0.1" +# -- 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"] -# Enable MathJax for Math -extensions = [ - "sphinx.ext.mathjax", - "sphinx.ext.intersphinx", - "sphinx_copybutton", -] - -# 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 = [ - "_build", - "Thumbs.db", - ".DS_Store", - "install/custom.rst", -] - -intersphinx_mapping = { - "sphinx": ("http://www.sphinx-doc.org/en/master/", None), +# pydata_sphinx_theme reference: https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html +html_theme = "pydata_sphinx_theme" +html_theme_options = { + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/jupyterhub/the-littlest-jupyterhub", + "icon": "fab fa-github-square", + }, + { + "name": "Discourse", + "url": "https://discourse.jupyter.org/c/jupyterhub/tljh/13", + "icon": "fab fa-discourse", + }, + ], + "use_edit_page_button": True, +} +html_context = { + "github_user": "jupyterhub", + "github_repo": "the-littlest-jupyterhub", + "github_version": "main", + "doc_path": "docs", } -intersphinx_cache_limit = 90 # days -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" +# -- 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/the-littlest-jupyterhub/pull/", # too many PRs in changelog + "https://github.com/jupyterhub/the-littlest-jupyterhub/compare/", # too many comparisons in changelog +] +linkcheck_anchors_ignore = [ + "/#!", + "/#%21", +] -html_theme = "pydata_sphinx_theme" -html_logo = "images/logo/logo.png" -html_favicon = "images/logo/favicon.ico" +# -- Options for the opengraph extension ------------------------------------- +# ref: https://github.com/wpilibsuite/sphinxext-opengraph#options +# +# ogp_site_url is set automatically by RTD +ogp_image = "_static/logo.png" +ogp_use_first_image = True -# 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". -# Do this only if _static exists, otherwise this will error -here = os.path.dirname(os.path.abspath(__file__)) -if os.path.exists(os.path.join(here, "_static")): - 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 = { + # "old-file": "new-folder/new-file-name", +} diff --git a/docs/requirements.txt b/docs/requirements.txt index b55f0e3..7d2b038 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,6 @@ -sphinx>=2 -sphinx-autobuild -sphinx_copybutton pydata-sphinx-theme +sphinx>=4 +sphinx_copybutton +sphinx-autobuild +sphinxext-opengraph +sphinxext-rediraffe From c49eae65bb5aa17308e8a6f7f9efb5c002807a28 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 28 Nov 2022 09:33:51 +0100 Subject: [PATCH 7/7] docs: update rtd config --- .readthedocs.yaml | 22 +++++----------------- 1 file changed, 5 insertions(+), 17 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 3cdde0f..7440511 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,29 +1,17 @@ # Configuration on how ReadTheDocs (RTD) builds our documentation # ref: https://readthedocs.org/projects/the-littlest-jupyterhub/ # ref: https://docs.readthedocs.io/en/stable/config-file/v2.html - -# Required (RTD configuration version) +# version: 2 -# Set the version of Python and other tools you might need -build: - os: ubuntu-20.04 - tools: - python: "3.9" - -# Build documentation in the docs/ directory with Sphinx sphinx: configuration: docs/conf.py -# Optionally build your docs in additional formats such as PDF and ePub -formats: [] +build: + os: ubuntu-22.04 + tools: + python: "3.11" python: install: - # WARNING: This requirements file will be installed without the pip - # --upgrade flag in an existing environment. This means that if a - # package is specified without a lower boundary, we may end up - # accepting the existing version. - # - # ref: https://github.com/readthedocs/readthedocs.org/blob/0e3df509e7810e46603be47d268273c596e68455/readthedocs/doc_builder/python_environments.py#L335-L344 - requirements: docs/requirements.txt