Bootstrap a new documentation

Markdown format is kept as a main format, relying on python sphinx and
myst_parser to render an HTML documentation if needed.

Note that while markdown is more readable as raw text, it's a way simpler
syntax that lacks a lot of features that reStructuredText offers.  Relying on
sphinx gives us an opportunity to later write parts of the documentation in
reStructuredText if needed, but also offers other appealing features like
multilingual documentation that we may reintroduce in a near future.

Readthedocs is the expected target, so use its theme and follow its
recommendation about pinning various requirement versions.

The documentation can be built locally easily using

make -C docs/ html

The rendered documentation will be generated in docs/html/_build/html

Note that you need to have all python prerequirements installed, which can be
done using:

pip install -r docs/requirements.txt

If you need to update the requirements (which shouldn't be needed frequently),
update the docs/requirements.in and generate the target docs/requirements.txt
using pip-compile.  See the link about this tool below for more details on how
to use it.

As a first step, simply duplicate the README.md for the documentation.

References if you're interested in the various design choices:

- quickstart for RTD with sphinx: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
- reproducible builds: https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
- myst parser: https://myst-parser.readthedocs.io
- pip-tools / pip-compile: https://pip-tools.readthedocs.io
- RTD sphinx theme: https://sphinx-rtd-theme.readthedocs.io

Pull request #125, fixes #123

Backpatch-through: 14
Reviewed-by: Michael Paquier

.gitignore

@@ -12,4 +12,7 @@ regression.*
 /log/
 /results/
 /tmp_check/
-/RPMS/
+/RPMS/
+
+# Documentation artifacts
+docs/_build

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# 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
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README

@@ -0,0 +1,49 @@
+pg_hint_plan documentation
+==========================
+
+Introduction
+------------
+
+Markdown format is kept as a main format, relying on python sphinx and
+myst_parser to render an HTML documentation if needed.
+
+Note that while markdown is more readable as raw text, it's a way simpler
+syntax that lacks a lot of features that reStructuredText offers.  Relying on
+sphinx gives us an opportunity to later write parts of the documentation in
+reStructuredText if needed, but also offers other appealing features like
+multilingual documentation that we may reintroduce in a near future.
+
+Readthedocs is the expected target, so use its theme and follow its
+recommendation about pinning various requirement versions.
+
+Building the doc locally
+------------------------
+
+The documentation can be built locally easily using
+
+make -C docs/ html
+
+The rendered documentation will be generated in docs/html/_build/html
+
+Note that you need to have all python prerequirements installed, which can be
+done using:
+
+pip install -r docs/requirements.txt
+
+If you need to update the requirements (which shouldn't be needed frequently),
+update the docs/requirements.in and generate the target docs/requirements.txt
+using pip-compile.  See the link about this tool below for more details on how
+to use it.
+
+As a first step, simply duplicate the README.md for the documentation.
+
+References
+----------
+
+References if you're interested in the various design choices:
+
+- quickstart for RTD with sphinx: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
+- reproducible builds: https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+- myst parser: https://myst-parser.readthedocs.io
+- pip-tools / pip-compile: https://pip-tools.readthedocs.io
+- RTD sphinx theme: https://sphinx-rtd-theme.readthedocs.io

docs/conf.py

@@ -0,0 +1,27 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'pg_hint_plan'
+copyright = '2012-2023, NIPPON TELEGRAPH AND TELEPHONE CORPORATION'
+author = 'NIPPON TELEGRAPH AND TELEPHONE CORPORATION'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinx_rtd_theme', 'myst_parser']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	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.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.in

@@ -0,0 +1,10 @@
+# RTD only supports sphinx up to 5.3.0
+sphinx==5.3.0
+
+# those are sphinx dependencies, but unfortunately RTD doesn't support the
+# latest versions, so we need to explicitly pin them
+sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.0
+
+sphinx_rtd_theme
+myst_parser

docs/requirements.txt

@@ -0,0 +1,77 @@
+#
+# This file is autogenerated by pip-compile with Python 3.9
+# by the following command:
+#
+#    pip-compile --resolver=backtracking requirements.in
+#
+alabaster==0.7.13
+    # via sphinx
+babel==2.12.1
+    # via sphinx
+certifi==2022.12.7
+    # via requests
+charset-normalizer==3.0.1
+    # via requests
+docutils==0.19
+    # via
+    #   myst-parser
+    #   sphinx
+idna==3.4
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+importlib-metadata==6.0.0
+    # via sphinx
+jinja2==3.1.2
+    # via
+    #   myst-parser
+    #   sphinx
+markdown-it-py==2.2.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+markupsafe==2.1.2
+    # via jinja2
+mdit-py-plugins==0.3.4
+    # via myst-parser
+mdurl==0.1.2
+    # via markdown-it-py
+myst-parser==0.19.0
+    # via -r requirements.in
+packaging==23.0
+    # via sphinx
+pygments==2.14.0
+    # via sphinx
+pyyaml==6.0
+    # via myst-parser
+requests==2.28.2
+    # via sphinx
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==5.3.0
+    # via
+    #   -r requirements.in
+    #   myst-parser
+    #   sphinx-rtd-theme
+sphinx-rtd-theme==0.5.1
+    # via -r requirements.in
+sphinxcontrib-applehelp==1.0.2
+    # via
+    #   -r requirements.in
+    #   sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.0
+    # via
+    #   -r requirements.in
+    #   sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
+urllib3==1.26.14
+    # via requests
+zipp==3.15.0
+    # via importlib-metadata