From 90811196d7da6b4d7166885f5d8fb1fb3c983679 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Thu, 17 Nov 2022 13:00:22 +0100 Subject: [PATCH 1/4] docs: remove unused alabaster_jupyterhub requirement --- docs/requirements.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 54c6f363..03dd2da8 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,6 +1,5 @@ -r ../requirements.txt -alabaster_jupyterhub autodoc-traits myst-parser pre-commit From 26e5efeec4f69e451aae47afffd0c8402864b4d8 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Thu, 17 Nov 2022 13:08:17 +0100 Subject: [PATCH 2/4] docs: cleanup unused config for htmlhelp, latex, manual --- docs/source/conf.py | 72 ++------------------------------------------- 1 file changed, 2 insertions(+), 70 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 63d61624..39a84fc8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -7,9 +7,6 @@ sys.path.insert(0, os.path.abspath('.')) # -- General configuration ------------------------------------------------ -# Minimal Sphinx version -needs_sphinx = '1.4' - # Sphinx extension modules extensions = [ 'sphinx.ext.autodoc', @@ -27,7 +24,7 @@ myst_enable_extensions = [ 'deflist', ] # The master toctree document. -master_doc = 'index' +root_doc = master_doc = 'index' # General information about the project. project = 'JupyterHub' @@ -118,11 +115,10 @@ def setup(app): source_suffix = ['.rst', '.md'] -# source_encoding = 'utf-8-sig' # -- Options for HTML output ---------------------------------------------- -# The theme to use for HTML and HTML Help pages. +# The theme to use for HTML html_theme = 'pydata_sphinx_theme' html_logo = '_static/images/logo/logo.png' @@ -131,8 +127,6 @@ html_favicon = '_static/images/logo/favicon.ico' # Paths that contain custom static files (such as style sheets) html_static_path = ['_static'] -htmlhelp_basename = 'JupyterHubdoc' - html_theme_options = { "icon_links": [ { @@ -157,68 +151,6 @@ html_context = { "doc_path": "docs", } -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # 'papersize': 'letterpaper', - # 'pointsize': '10pt', - # 'preamble': '', - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - ( - master_doc, - 'JupyterHub.tex', - 'JupyterHub Documentation', - 'Project Jupyter team', - 'manual', - ) -] - -# latex_logo = None -# latex_use_parts = False -# latex_show_pagerefs = False -# latex_show_urls = False -# latex_appendices = [] -# latex_domain_indices = True - - -# -- manual page output ------------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [(master_doc, 'jupyterhub', 'JupyterHub Documentation', [author], 1)] - -# man_show_urls = False - - -# -- Texinfo output ----------------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - master_doc, - 'JupyterHub', - 'JupyterHub Documentation', - author, - 'JupyterHub', - 'One line description of project.', - 'Miscellaneous', - ) -] - -# texinfo_appendices = [] -# texinfo_domain_indices = True -# texinfo_show_urls = 'footnote' -# texinfo_no_detailmenu = False - - # -- Epub output -------------------------------------------------------- # Bibliographic Dublin Core info. From 1c9499e91ec67105b9e75515ef68b259665e2c5e Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Thu, 17 Nov 2022 13:09:06 +0100 Subject: [PATCH 3/4] docs: remove epub documentation build --- .readthedocs.yaml | 9 ++++++++- docs/source/conf.py | 11 ----------- 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index c1e09b1a..31ff7a72 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,3 +1,7 @@ +# Configuration on how ReadTheDocs (RTD) builds our documentation +# ref: https://readthedocs.org/projects/jupyterhub/ +# ref: https://docs.readthedocs.io/en/stable/config-file/v2.html +# version: 2 sphinx: @@ -16,5 +20,8 @@ python: - requirements: docs/requirements.txt formats: + # Adding htmlzip enables a Downloads section in the rendered website's RTD + # menu where the html build can be downloaded. This doesn't require any + # additional configuration in docs/source/conf.py. + # - htmlzip - - epub diff --git a/docs/source/conf.py b/docs/source/conf.py index 39a84fc8..03044de1 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -151,17 +151,6 @@ html_context = { "doc_path": "docs", } -# -- Epub output -------------------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project -epub_author = author -epub_publisher = author -epub_copyright = copyright - -# A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] - # -- Intersphinx ---------------------------------------------------------- intersphinx_mapping = { From 7f3fd7e3cc87aaab3255a3c73f538ada678859cf Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Thu, 17 Nov 2022 13:38:25 +0100 Subject: [PATCH 4/4] docs: fix broken links and formatting errors --- docs/source/admin/upgrading.rst | 4 +++- docs/source/getting-started/config-basics.md | 4 ++-- docs/source/reference/config-sudo.md | 2 +- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/source/admin/upgrading.rst b/docs/source/admin/upgrading.rst index fb76a94a..fe793915 100644 --- a/docs/source/admin/upgrading.rst +++ b/docs/source/admin/upgrading.rst @@ -43,8 +43,10 @@ Backup database & config Before doing an upgrade, it is critical to back up: #. Your JupyterHub database (SQLite by default, or MySQL / Postgres if you used those). -If you use SQLite (the default), you should backup the ``jupyterhub.sqlite`` file. + If you use SQLite (the default), you should backup the ``jupyterhub.sqlite`` file. + #. Your ``jupyterhub_config.py`` file. + #. Your users' home directories. This is unlikely to be affected directly by a JupyterHub upgrade, but we recommend a backup since user data is critical. diff --git a/docs/source/getting-started/config-basics.md b/docs/source/getting-started/config-basics.md index 03495a62..7f838871 100644 --- a/docs/source/getting-started/config-basics.md +++ b/docs/source/getting-started/config-basics.md @@ -77,8 +77,8 @@ jupyterhub --Spawner.notebook_dir='~/assignments' ## Configure for various deployment environments The default authentication and process spawning mechanisms can be replaced, and -specific [authenticators](./authenticators-users-basics) and -[spawners](./spawners-basics) can be set in the configuration file. +specific [authenticators](authenticators-users-basics) and +[spawners](spawners-basics) can be set in the configuration file. This enables JupyterHub to be used with a variety of authentication methods or process control and deployment environments. [Some examples](../reference/config-examples), meant as illustrations, are: diff --git a/docs/source/reference/config-sudo.md b/docs/source/reference/config-sudo.md index 2962ae97..57d6a385 100644 --- a/docs/source/reference/config-sudo.md +++ b/docs/source/reference/config-sudo.md @@ -6,7 +6,7 @@ Only do this if you are very sure you must. ## Overview -There are many [Authenticators](./authenticators-users-basics) and [Spawners](./spawners-basics) available for JupyterHub. Some, such +There are many [Authenticators](../getting-started/authenticators-users-basics) and [Spawners](../getting-started/spawners-basics) available for JupyterHub. Some, such as [DockerSpawner](https://github.com/jupyterhub/dockerspawner) or [OAuthenticator](https://github.com/jupyterhub/oauthenticator), do not need any elevated permissions. This document describes how to get the full default behavior of JupyterHub while running notebook servers as real system users on a shared system, without