launchpad-reviewers team mailing list archive

[Jürgen Gmach <mp+411456@xxxxxxxxxxxxxxxxxx>]

Jürgen Gmach has proposed merging ~jugmac00/launchpad:create-documentation-via-tox into launchpad:master.

Commit message:
Update documentation building

- build documentation via `tox -e docs`
- pin documentation dependencies (requirements/docs.txt)
- update dependencies via `tox -e update-docs`
- fix broken Read the Docs build by pinning documentation dependencies

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~jugmac00/launchpad/+git/launchpad/+merge/411456
-- 
Your team Launchpad code reviewers is requested to review the proposed merge of ~jugmac00/launchpad:create-documentation-via-tox into launchpad:master.

diff --git a/.gitignore b/.gitignore
index 6cd08b9..3b2e7d2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -74,3 +74,4 @@ callgrind.out.*
 yarn/node_modules
 /wheels
 requirements/combined.txt
+.tox/
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 0000000..91b6a9c
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,5 @@
+version: 2
+
+python:
+   install:
+   - requirements: requirements/docs.txt
diff --git a/doc/README b/doc/README
index 84de5de..bacd86a 100644
--- a/doc/README
+++ b/doc/README
@@ -1,5 +1,7 @@
 This directory contains general system-level documentation for Launchpad.
 
+To build the documentation locally just run ``tox -e docs``.
+
 You can also find general documentation on <https://dev.launchpad.net> and
 documentation on specific parts of the system in doctests (look for *.txt
 files) or in docstrings.
diff --git a/doc/conf.py b/doc/conf.py
index c4a73e4..038ab03 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -39,8 +39,8 @@ source_suffix = '.txt'
 master_doc = 'index'
 
 # General information about the project.
-project = u'Launchpad'
-copyright = u'2004-2019, Canonical Ltd.'
+project = 'Launchpad'
+copyright = '2004-2021, Canonical Ltd.'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -120,7 +120,7 @@ html_theme = 'default'
 # 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']
+html_static_path = []
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -178,10 +178,6 @@ htmlhelp_basename = 'Launchpaddoc'
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author,
 #  documentclass [howto/manual]).
-latex_documents = [
-  ('index', 'Launchpad.tex', u'Launchpad Documentation',
-   u'The Launchpad Developers', 'manual'),
-]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
@@ -211,11 +207,6 @@ latex_documents = [
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    ('index', 'launchpad', u'Launchpad Documentation',
-     [u'The Launchpad Developers'], 1)
-]
-
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
diff --git a/requirements/docs.in b/requirements/docs.in
new file mode 100644
index 0000000..2806c16
--- /dev/null
+++ b/requirements/docs.in
@@ -0,0 +1 @@
+Sphinx
diff --git a/requirements/docs.txt b/requirements/docs.txt
new file mode 100644
index 0000000..eefeb0f
--- /dev/null
+++ b/requirements/docs.txt
@@ -0,0 +1,55 @@
+#
+# This file is autogenerated by pip-compile with python 3.8
+# To update, run:
+#
+#    pip-compile --output-file=requirements/docs.txt requirements/docs.in
+#
+alabaster==0.7.12
+    # via sphinx
+babel==2.9.1
+    # via sphinx
+certifi==2021.10.8
+    # via requests
+charset-normalizer==2.0.7
+    # via requests
+docutils==0.17.1
+    # via sphinx
+idna==3.3
+    # via requests
+imagesize==1.2.0
+    # via sphinx
+jinja2==3.0.2
+    # via sphinx
+markupsafe==2.0.1
+    # via jinja2
+packaging==21.2
+    # via sphinx
+pygments==2.10.0
+    # via sphinx
+pyparsing==2.4.7
+    # via packaging
+pytz==2021.3
+    # via babel
+requests==2.26.0
+    # via sphinx
+snowballstemmer==2.1.0
+    # via sphinx
+sphinx==4.2.0
+    # via -r requirements/docs.in
+sphinxcontrib-applehelp==1.0.2
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.0
+    # via 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.7
+    # via requests
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools
diff --git a/tox.ini b/tox.ini
new file mode 100644
index 0000000..c8edceb
--- /dev/null
+++ b/tox.ini
@@ -0,0 +1,17 @@
+[tox]
+
+[testenv:docs]
+basepython = python3
+skip_install = true
+deps =
+    -r {toxinidir}/requirements/docs.txt
+commands =
+    #pip install -r docs-requirements.txt
+    sphinx-build -b html {toxinidir}/doc/ {toxinidir}/doc/_build/html
+
+[testenv:update-docs]
+skip_install = true
+deps =
+    pip-tools
+commands =
+    pip-compile --upgrade {toxinidir}/requirements/docs.in --output-file {toxinidir}/requirements/docs.txt