From 6f6301edd7451298a3f9e782f391e0b1ed713530 Mon Sep 17 00:00:00 2001 From: Brian Koopman Date: Tue, 26 Oct 2021 17:06:50 -0400 Subject: [PATCH 1/2] Pin docutils and add readthedocs config file A recent update in docutils breaks builds on readthedocs. This is the suggested work around from readthedocs [1]. [1] - https://github.com/readthedocs/readthedocs.org/issues/8616 --- .readthedocs.yaml | 6 ++++++ docs/requirements.txt | 1 + 2 files changed, 7 insertions(+) create mode 100644 .readthedocs.yaml create mode 100644 docs/requirements.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..3354cd09d --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,6 @@ +version: 2 + +python: + install: + - requirements: docs/requirements.txt + - requirements: requirements.txt diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..93120e66c --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +docutils<0.18 From 202d0342204c7a206c5e19bc436f8f83e5a126a7 Mon Sep 17 00:00:00 2001 From: Brian Koopman Date: Wed, 27 Oct 2021 18:08:35 -0400 Subject: [PATCH 2/2] Pin all docs requirement versions and move to docs/requirements.txt Also update the documentation on how to build the docs, and explicitly define the readthedocs config. --- .readthedocs.yaml | 10 +++++++--- README.rst | 6 ++++-- docs/requirements.txt | 4 +++- requirements.txt | 2 +- 4 files changed, 15 insertions(+), 7 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 3354cd09d..9a17f94d9 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,6 +1,10 @@ version: 2 +sphinx: + configuration: docs/conf.py + python: - install: - - requirements: docs/requirements.txt - - requirements: requirements.txt + version: 3.7 + install: + - requirements: docs/requirements.txt + - requirements: requirements.txt diff --git a/README.rst b/README.rst index 29b9ffa56..3c8974f62 100644 --- a/README.rst +++ b/README.rst @@ -70,10 +70,12 @@ be considered unstable. Documentation ------------- -The SOCS documentation can be built using sphinx once you have performed the -installation:: +The SOCS documentation can be built using Sphinx. There is a separate +``requirements.txt`` file in the ``docs/`` directory to install Sphinx and any +additional documentation dependencies:: cd docs/ + pip3 install -r requirements.txt make html You can then open ``docs/_build/html/index.html`` in your preferred web diff --git a/docs/requirements.txt b/docs/requirements.txt index 93120e66c..6de08b019 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1 +1,3 @@ -docutils<0.18 +sphinx==4.2.0 +sphinx_rtd_theme==1.0.0 +sphinx-argparse==0.3.1 diff --git a/requirements.txt b/requirements.txt index 4edf49168..c2d2a513a 100644 --- a/requirements.txt +++ b/requirements.txt @@ -19,7 +19,7 @@ pysnmp pysmi # Docs -sphinx_rtd_theme +# see docs/requirements.txt # testing pytest