Merge pull request #4222 from consideRatio/pr/docs-maintenance

docs: sphinx config cleanup, removing epub build, fix build warnings

.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

docs/requirements.txt

@@ -1,6 +1,5 @@
 -r ../requirements.txt
 
-alabaster_jupyterhub
 autodoc-traits
 myst-parser
 pre-commit

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.
 

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,79 +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.
-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 = {

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:

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