chore: upgrade sphinx to v6 (#218)

* chore: upgrade sphinx to v6

* chore: allow writing docs using markdown

Author: jooola

Makefile

@@ -14,7 +14,8 @@ coverage: venv
 	venv/bin/coverage html
 	xdg-open htmlcov/index.html
 
-docs:
+export SPHINXBUILD=../venv/bin/sphinx-build
+docs: venv
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
 	xdg-open docs/_build/html/index.html

docs/Makefile

@@ -1,10 +1,10 @@
 # Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = python -msphinx
-SPHINXPROJ    = hcloud
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 

docs/conf.py

@@ -1,162 +1,56 @@
-#!/usr/bin/env python3
-#
-# hcloud documentation build configuration file, created by
-# sphinx-quickstart on Fri Jun  9 13:47:02 2017.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# If extensions (or modules to document with autodoc) are in another
-# directory, add these directories to sys.path here. If the directory is
-# relative to the documentation root, use os.path.abspath to make it
-# absolute, like shown here.
-#
 import os
 import sys
+from datetime import datetime
 
 sys.path.insert(0, os.path.abspath(".."))
 from hcloud.__version__ import VERSION  # noqa
 
-# -- General configuration ---------------------------------------------
-
-# If your documentation needs a minimal Sphinx _version, state it here.
+# Configuration file for the Sphinx documentation builder.
 #
-# needs_sphinx = '1.0'
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# 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.autodoc", "sphinx.ext.viewcode"]
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
-# source_suffix = '.rst'
-
-# The master toctree document.
-master_doc = "index"
-
-# General information about the project.
 project = "Hetzner Cloud Python"
-copyright = "2019, Hetzner Cloud GmbH"
 author = "Hetzner Cloud GmbH"
+copyright = f"{datetime.now().year}, {author}"
 
-# The version info for the project you're documenting, acts as replacement
-# for |version| and |release|, also used in various other places throughout
-# the built documents.
-#
-# The short X.Y _version.
 version = VERSION
-# The full _version, including alpha/beta/rc tags.
 release = VERSION
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = "en"
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
+extensions = ["myst_parser", "sphinx.ext.autodoc", "sphinx.ext.viewcode"]
+templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
 
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
+# A boolean that decides whether module names are prepended to all object names (for
+# object types where a “module” of some kind is defined), e.g. for py:function
+# directives. Default is True.
 add_module_names = False
 
-# -- Options for HTML output -------------------------------------------
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
 html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+
 html_logo = "_static/logo-hetzner-online.svg"
 html_favicon = "_static/favicon.png"
-# Theme options are theme-specific and customize the look and feel of a
-# theme further.  For a list of options available for each theme, see the
-# documentation.
-#
-html_theme_options = {"logo_only": True, "style_nav_header_background": "#EFEFEF"}
+# Theme options are theme-specific and customize the look and feel of a theme further.
+# For a list of options available for each theme, see the documentation.
+html_theme_options = {
+    "logo_only": True,
+    "style_nav_header_background": "#efefef",
+}
 html_css_files = [
     "custom.css",
 ]
-
-# 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 HTMLHelp output ---------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = "hclouddoc"
-
-# -- Options for LaTeX output ------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-    # Latex figure (float) alignment
-    #
-    # '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,
-        "hcloud.tex",
-        "Hetzner Cloud Python Documentation",
-        "Hetzner Cloud GmbH",
-        "manual",
-    )
-]
-
-# -- Options for manual page output ------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "Hetzner Cloud Python Documentation", [author], 1)]
-
-# -- Options for 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,
-        "Hetzner Cloud Python Documentation",
-        author,
-        "HCloud-python is a library for the Hetzner Cloud API.",
-        "Miscellaneous",
-    )
-]
-
-source_suffix = [".rst"]

docs/make.bat

@@ -5,32 +5,31 @@ pushd %~dp0
 REM Command file for Sphinx documentation
 
 if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=python -msphinx
+	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=.
 set BUILDDIR=_build
-set SPHINXPROJ=hcloud
-
-if "%1" == "" goto help
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.
-	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
-	echo.then set the SPHINXBUILD environment variable to point to the full
-	echo.path of the 'sphinx-build' executable. Alternatively you may add the
-	echo.Sphinx directory to PATH.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
+	echo.https://www.sphinx-doc.org/
 	exit /b 1
 )
 
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
 :help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :end
 popd

setup.py

@@ -42,8 +42,9 @@
     ],
     extras_require={
         "docs": [
-            "sphinx==1.8.1",
-            "sphinx-rtd-theme==0.4.2",
+            "sphinx>=6.2.1,<7.0",
+            "sphinx-rtd-theme>=1.2.2,<1.3",
+            "myst-parser>=2.0.0,<2.1",
         ],
         "test": [
             "coverage>=7.2.7,<7.3",