Merge ~jugmac00/launchpadlib:add-configuration-file-for-rtd into launchpadlib:main

[Jürgen Gmach]

Add configuration file for Read the Docs

[Ines Almeida (ines-almeida)]

Looks good to me, although I'm not into the details of readthedocs.yaml

Does the python section of the config basically tell it to build the docs from that path, to a `docs` directory, using pip?

I notice the other `.readthedocs.yaml` in our repos don't use `fail_on_warning`. I think it makes sense to add it, but maybe we also want to add it in the other ones to keep them consistent!

review: Approve

[Jürgen Gmach (jugmac00)]

> Does the python section of the config basically tell it to build the docs from that path, to a `docs` directory, using pip?

No.

This refers to the `extras_require` section in the `setup.py`.
https://git.launchpad.net/launchpadlib/tree/setup.py#n93

So the mentioned specification would translate to

```
pip install .[docs]
```

That is install the package plus the extra requirements specified in the `docs` `extras_require` section.

Another example would be the wtforms library - when you want to have the email validator enabled, you need to install it via `pip install wtforms[email_validator]`
https://github.com/wtforms/wtforms/blob/0524993ee57a957c8444df2b090c00464ef9bb2a/setup.cfg#L37

> I notice the other `.readthedocs.yaml` in our repos don't use `fail_on_warning`. I think it makes sense to add it, but maybe we also want to add it in the other ones to keep them consistent!

Indeed, it makes sense to use it, as otherwise technical debt can pile or even worse things break unnoticed.

Currently, it is very tedious to apply changes to all our repositories, that is why I created an item for the next roadmap cycle to introduce tooling for that.
https://docs.google.com/spreadsheets/d/1rmlPtCWr-nlIDE26Et_okt4yC4RRQX5r6wLik-M9WpM/edit#gid=1800655972

[Ines Almeida (ines-almeida)]

And thank you for clarifying!
And I am completely on board with the road map item suggestion :)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 0000000..09c7853
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.8"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+sphinx:
+  configuration: src/launchpadlib/docs/conf.py
+  fail_on_warning: true
diff --git a/src/launchpadlib/docs/conf.py b/src/launchpadlib/docs/conf.py
index 05da684..268a8ce 100644
--- a/src/launchpadlib/docs/conf.py
+++ b/src/launchpadlib/docs/conf.py
@@ -65,7 +65,7 @@ release = __version__
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
diff --git a/tox.ini b/tox.ini
index d71e61d..aaa62c9 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,6 +1,7 @@
 [tox]
 envlist =
     py27,py35,py36,py37,py38,py39,py310,py311,lint,docs
+requires = virtualenv<20.22
 
 [testenv]
 deps =
@@ -18,7 +19,7 @@ passenv =
     http_proxy
     https_proxy
 basepython =
-    python3.8
+    python3.8  # align with .launchpad.yaml
 deps =
     pre-commit
 commands =
@@ -26,7 +27,7 @@ commands =
 
 [testenv:docs]
 basepython =
-    python2.7
+    python3.8  # align with .launchpad.yaml
 commands =
     sphinx-build -b html -d src/launchpadlib/docs/_build/doctrees src/launchpadlib/docs src/launchpadlib/docs/_build/html
 deps =