Merge ~lgp171188/rutabaga:add-readthedocs-yaml into rutabaga:master

[Guruprasad]

Add a .readthedocs.yaml configuration file

And add tox.ini to build the docs using tox

[Jürgen Gmach (jugmac00)]

Thanks for working on this!

I feel slightly uneasy to pin to a very outdated Sphinx version, which even is possibly vulnerable to a couple of security issues, which I have not checked in detail:
https://security.snyk.io/package/pip/sphinx

Could you elaborate what the issue was with building docs with a recent version?
If this is related to an upstream package, we need to report the issue there and think about what to do.

Even if we agree upon merging this as is, we should add a task to our Jira board, and put in an upcoming pulse.

[Jürgen Gmach (jugmac00)]

Guruprasad proposed a fix in the upstream package, see https://github.com/Cornices/cornice.ext.sphinx/pull/26

[Guruprasad (lgp171188)]

Jürgen, the upstream PR has been merged and the maintainer published a new release, 0.4, which allows us to upgrade Sphinx and remove all the pins. Can you re-review?

[Jürgen Gmach (jugmac00)]

Thank you, looks great!

review: Approve

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 0000000..126cfe1
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
diff --git a/docs/conf.py b/docs/conf.py
index bb6d11e..0da1f7a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -30,7 +30,7 @@ sys.path.insert(0, os.path.abspath('../'))
 # 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', 'cornice.ext.sphinxext']
+extensions = ['sphinx.ext.autodoc', 'cornice_sphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -59,7 +59,7 @@ release = '0.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-#language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -129,7 +129,7 @@ html_theme = 'alabaster'
 # 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 = []
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
diff --git a/setup.py b/setup.py
index da1216e..c27f108 100644
--- a/setup.py
+++ b/setup.py
@@ -20,16 +20,23 @@ requires = [
     'PyYAML',
     'waitress',
     ]
+docs_requires = [
+    'cornice',
+    'cornice-sphinx',
+    'Jinja2',
+    'PyYAML',
+    'Sphinx',
+]
+deploy_requires = [
+    'envdir',
+    'gunicorn',
+    ]
 test_requires = [
     'fixtures',
     'flake8',
     'testtools',
     'webtest',
     ]
-deploy_requires = [
-    'envdir',
-    'gunicorn',
-    ]
 
 setup(
     name='rutabaga',
@@ -58,8 +65,10 @@ setup(
     install_requires=requires,
     tests_require=test_requires,
     extras_require=dict(
+        deploy=deploy_requires,
+        docs=docs_requires,
         test=test_requires,
-        deploy=deploy_requires),
+    ),
     test_suite='rutabaga',
     entry_points="""\
       [paste.app_factory]
diff --git a/tox.ini b/tox.ini
new file mode 100644
index 0000000..8a2d6e0
--- /dev/null
+++ b/tox.ini
@@ -0,0 +1,11 @@
+[tox]
+envlist =
+    docs
+
+[testenv:docs]
+basepython =
+    python3.11
+commands =
+    sphinx-build -b html -d docs/_build/doctrees docs/ docs/_build/html
+deps =
+    .[docs]