Fix documentation builds from further breaking RTD API changes

Handle problems with build.os config requirement and an index.rst requirement. Use the opportunity to add standard documentation and order of definitions in the updated YAML file as well as standard "docs" folder name.
intra2net · Apr 29, 2024 · 8ddc791 · 8ddc791
1 parent 4d3608e
commit 8ddc791
Show file tree

Hide file tree

Showing 38 changed files with 81 additions and 19 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,16 +1,31 @@
-version: 2
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-python:
-  version: 3.7
-  install:
-     - requirements: requirements_pip.txt
-     # TODO: pip-crippled vt dependency and no RTD scripts supported
-     #- method: pip
-     #  path: .
+# Required
+version: 2
 
-formats: all
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
 
+# Build documentation in the docs/api directory with Sphinx
 sphinx:
   builder: html
-  configuration: doc/api/conf.py
+  configuration: docs/api/conf.py
+  # TODO: investigate warnings
   fail_on_warning: false
+
+# Build docs in additional formats such as PDF and ePub
+formats: all
+
+# Specify dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+#python:
+#  install:
+#      TODO: pip-crippled vt dependency (104) and no RTD scripts supported
+#     - requirements: requirements_pip.txt
+#     - method: pip
+#       path: .
diff --git a/doc/api/Makefile → docs/api/Makefile b/doc/api/Makefile → docs/api/Makefile
diff --git a/doc/api/_static → docs/api/_static b/doc/api/_static → docs/api/_static
diff --git a/doc/api/conf.py → docs/api/conf.py b/doc/api/conf.py → docs/api/conf.py
diff --git a/doc/api/generate_api.sh → docs/api/generate_api.sh b/doc/api/generate_api.sh → docs/api/generate_api.sh
@@ -1,15 +1,18 @@
 #!/bin/bash
+# Run this script when producing new documentation to submit to RTD.
+
+set -e
 
 # produce rst files for the modules
 sphinx-apidoc -e -f -o . ../../avocado_i2n || die "No rst files could be generated"
 
 # move all rst files to source directory to integrate with RTD
-rm -fr source README.rst
+rm -fr source index.rst
 mkdir source || die "No source directory to move rst files to"
 mv *.rst source
 
 # produce HTML documentation from the rst files
 make html
 
 # use README as index page for RTD (needs MD-RST compatibility)
-pandoc ../../README.md --from markdown --to rst -s -o README.rst
+pandoc ../../README.md --from markdown --to rst -s -o index.rst
diff --git a/doc/api/README.rst → docs/api/index.rst b/doc/api/README.rst → docs/api/index.rst
@@ -4,14 +4,58 @@ avocado-i2n
 *Plugins for avocado extending avocado-vt with automated vm state setup,
 inheritance, and traversal*
 
-|Build Status| |Documentation Status| |Language grade: Python| |codecov|
+|GH Actions| |Documentation Status| |CodeQL| |codecov|
 
 This file provides a brief overview of the core concepts behind the
 current plugin and hopefully a compact explanation of how tests are
 being run.
 
-Motivation and background
--------------------------
+Motivation
+----------
+
+Let’s say that we write an integration test about some web site that has
+to validate the system behaves as expected. Imagine we have a web page
+with a button that we want to click on and check that a dialog that
+appears once we click is exactly as it should be. So far it is not too
+hard to write a test about this - we validate the preconditions like the
+button that has to be present, operate on top, and validate the
+postconditions like the dialog appearing afterwards. What if there is
+also a checkbox on the dialog that the user would check to see some
+warning text appear? Still easy enough as we extend the original test to
+also make sure the checkbox is there, check it, then make sure the
+warning is there. Now let’s complicate this a bit further - imagine
+there are instead two checkboxes on the dialog that we should also
+validate but separately. If we check the first checkbox some text will
+be displayed but if we check the second checkbox a different text will
+be displayed instead. How do we validate both use cases? Well, we write
+a test like the original one that expects a button, clicks on it, then
+expects the first checkbox and checks it to validate the first outcome
+and another one to do the same things but check the second checkbox and
+validate the second outcome. Ok, two integration tests for the two use
+cases. But what if they are a hundred and we have to check the first
+button and validate the dialog each time? Could we do better than this
+by reusing the first step in the process? We could try and complicate
+our initial test a bit by unchecking the first checkbox in order to
+check the second one and test for its outcome but there is a significant
+drawback here - unchecking the first checkbox is not a precondition for
+checking the second one and could affect its outcome in unforeseen ways.
+Furthermore, the test script could be come very complicated and
+convoluted over multiple such undo operations. There is a way around all
+of this though: what if we could click the button, validate the dialog
+has appeared, and then simply save the state of everything we are doing
+as a checkpoint that we can then branch into both use cases? Enter the
+Cartesian graph where the first step would be a separate simpler test
+and a setup node for two other simpler tests (leaf nodes) that would
+each simply start from the state the initial test left the environment
+in, check its respective checkbox and validate the text that would
+appear as result of that. None of the two tests would be in any way
+aware of the other one or affected by it. This is why we parse tests as
+graphs where tests could be requirements for other tests and it is up to
+us to consider all variants of our web site’s use cases and use graph
+test nodes as means to reuse steps of their scenarios.
+
+Background
+----------
 
 The two milestones and guiding principles for a test running process
 are:
@@ -615,11 +659,11 @@ This document concentrates only on the running part and the developing
 part is covered in multiple tutorials in the project wiki. Feel free to
 check it out.
 
-.. |Build Status| image:: https://travis-ci.org/intra2net/avocado-i2n.svg?branch=master
-   :target: https://travis-ci.org/intra2net/avocado-i2n
+.. |GH Actions| image:: https://github.com/intra2net/avocado-i2n/actions/workflows/ci.yml/badge.svg
+   :target: https://github.com/intra2net/avocado-i2n/actions/workflows/ci.yml
 .. |Documentation Status| image:: https://readthedocs.org/projects/avocado-i2n/badge/?version=latest
    :target: https://avocado-i2n.readthedocs.io/en/latest/?badge=latest
-.. |Language grade: Python| image:: https://img.shields.io/lgtm/grade/python/g/intra2net/avocado-i2n.svg?logo=lgtm&logoWidth=18
-   :target: https://lgtm.com/projects/g/intra2net/avocado-i2n/context:python
+.. |CodeQL| image:: https://github.com/intra2net/avocado-i2n/actions/workflows/codeql.yml/badge.svg
+   :target: https://github.com/intra2net/avocado-i2n/actions/workflows/codeql.yml
 .. |codecov| image:: https://codecov.io/gh/intra2net/avocado-i2n/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/intra2net/avocado-i2n
diff --git a/...pi/source/avocado_i2n.cartgraph.graph.rst → ...pi/source/avocado_i2n.cartgraph.graph.rst b/...pi/source/avocado_i2n.cartgraph.graph.rst → ...pi/source/avocado_i2n.cartgraph.graph.rst
diff --git a/...api/source/avocado_i2n.cartgraph.node.rst → ...api/source/avocado_i2n.cartgraph.node.rst b/...api/source/avocado_i2n.cartgraph.node.rst → ...api/source/avocado_i2n.cartgraph.node.rst
diff --git a/...i/source/avocado_i2n.cartgraph.object.rst → ...i/source/avocado_i2n.cartgraph.object.rst b/...i/source/avocado_i2n.cartgraph.object.rst → ...i/source/avocado_i2n.cartgraph.object.rst
diff --git a/doc/api/source/avocado_i2n.cartgraph.rst → docs/api/source/avocado_i2n.cartgraph.rst b/doc/api/source/avocado_i2n.cartgraph.rst → docs/api/source/avocado_i2n.cartgraph.rst
diff --git a/doc/api/source/avocado_i2n.cmd_parser.rst → docs/api/source/avocado_i2n.cmd_parser.rst b/doc/api/source/avocado_i2n.cmd_parser.rst → docs/api/source/avocado_i2n.cmd_parser.rst
diff --git a/...pi/source/avocado_i2n.intertest_setup.rst → ...pi/source/avocado_i2n.intertest_setup.rst b/...pi/source/avocado_i2n.intertest_setup.rst → ...pi/source/avocado_i2n.intertest_setup.rst
diff --git a/doc/api/source/avocado_i2n.loader.rst → docs/api/source/avocado_i2n.loader.rst b/doc/api/source/avocado_i2n.loader.rst → docs/api/source/avocado_i2n.loader.rst
diff --git a/doc/api/source/avocado_i2n.params_parser.rst → .../api/source/avocado_i2n.params_parser.rst b/doc/api/source/avocado_i2n.params_parser.rst → .../api/source/avocado_i2n.params_parser.rst
diff --git a/doc/api/source/avocado_i2n.plugins.auto.rst → docs/api/source/avocado_i2n.plugins.auto.rst b/doc/api/source/avocado_i2n.plugins.auto.rst → docs/api/source/avocado_i2n.plugins.auto.rst
diff --git a/doc/api/source/avocado_i2n.plugins.manu.rst → docs/api/source/avocado_i2n.plugins.manu.rst b/doc/api/source/avocado_i2n.plugins.manu.rst → docs/api/source/avocado_i2n.plugins.manu.rst
diff --git a/doc/api/source/avocado_i2n.plugins.rst → docs/api/source/avocado_i2n.plugins.rst b/doc/api/source/avocado_i2n.plugins.rst → docs/api/source/avocado_i2n.plugins.rst
diff --git a/...i/source/avocado_i2n.plugins.settings.rst → ...i/source/avocado_i2n.plugins.settings.rst b/...i/source/avocado_i2n.plugins.settings.rst → ...i/source/avocado_i2n.plugins.settings.rst
diff --git a/doc/api/source/avocado_i2n.rst → docs/api/source/avocado_i2n.rst b/doc/api/source/avocado_i2n.rst → docs/api/source/avocado_i2n.rst
diff --git a/doc/api/source/avocado_i2n.runner.rst → docs/api/source/avocado_i2n.runner.rst b/doc/api/source/avocado_i2n.runner.rst → docs/api/source/avocado_i2n.runner.rst
diff --git a/doc/api/source/avocado_i2n.states.btrfs.rst → docs/api/source/avocado_i2n.states.btrfs.rst b/doc/api/source/avocado_i2n.states.btrfs.rst → docs/api/source/avocado_i2n.states.btrfs.rst
diff --git a/doc/api/source/avocado_i2n.states.lvm.rst → docs/api/source/avocado_i2n.states.lvm.rst b/doc/api/source/avocado_i2n.states.lvm.rst → docs/api/source/avocado_i2n.states.lvm.rst
diff --git a/doc/api/source/avocado_i2n.states.lxc.rst → docs/api/source/avocado_i2n.states.lxc.rst b/doc/api/source/avocado_i2n.states.lxc.rst → docs/api/source/avocado_i2n.states.lxc.rst
diff --git a/doc/api/source/avocado_i2n.states.pool.rst → docs/api/source/avocado_i2n.states.pool.rst b/doc/api/source/avocado_i2n.states.pool.rst → docs/api/source/avocado_i2n.states.pool.rst
diff --git a/doc/api/source/avocado_i2n.states.qcow2.rst → docs/api/source/avocado_i2n.states.qcow2.rst b/doc/api/source/avocado_i2n.states.qcow2.rst → docs/api/source/avocado_i2n.states.qcow2.rst
diff --git a/...api/source/avocado_i2n.states.ramfile.rst → ...api/source/avocado_i2n.states.ramfile.rst b/...api/source/avocado_i2n.states.ramfile.rst → ...api/source/avocado_i2n.states.ramfile.rst
diff --git a/doc/api/source/avocado_i2n.states.rst → docs/api/source/avocado_i2n.states.rst b/doc/api/source/avocado_i2n.states.rst → docs/api/source/avocado_i2n.states.rst
diff --git a/doc/api/source/avocado_i2n.states.setup.rst → docs/api/source/avocado_i2n.states.setup.rst b/doc/api/source/avocado_i2n.states.setup.rst → docs/api/source/avocado_i2n.states.setup.rst
diff --git a/doc/api/source/avocado_i2n.states.vmnet.rst → docs/api/source/avocado_i2n.states.vmnet.rst b/doc/api/source/avocado_i2n.states.vmnet.rst → docs/api/source/avocado_i2n.states.vmnet.rst
diff --git a/...pi/source/avocado_i2n.vmnet.interface.rst → ...pi/source/avocado_i2n.vmnet.interface.rst b/...pi/source/avocado_i2n.vmnet.interface.rst → ...pi/source/avocado_i2n.vmnet.interface.rst
diff --git a/...pi/source/avocado_i2n.vmnet.netconfig.rst → ...pi/source/avocado_i2n.vmnet.netconfig.rst b/...pi/source/avocado_i2n.vmnet.netconfig.rst → ...pi/source/avocado_i2n.vmnet.netconfig.rst
diff --git a/doc/api/source/avocado_i2n.vmnet.network.rst → .../api/source/avocado_i2n.vmnet.network.rst b/doc/api/source/avocado_i2n.vmnet.network.rst → .../api/source/avocado_i2n.vmnet.network.rst
diff --git a/doc/api/source/avocado_i2n.vmnet.node.rst → docs/api/source/avocado_i2n.vmnet.node.rst b/doc/api/source/avocado_i2n.vmnet.node.rst → docs/api/source/avocado_i2n.vmnet.node.rst
diff --git a/doc/api/source/avocado_i2n.vmnet.rst → docs/api/source/avocado_i2n.vmnet.rst b/doc/api/source/avocado_i2n.vmnet.rst → docs/api/source/avocado_i2n.vmnet.rst
diff --git a/doc/api/source/avocado_i2n.vmnet.tunnel.rst → docs/api/source/avocado_i2n.vmnet.tunnel.rst b/doc/api/source/avocado_i2n.vmnet.tunnel.rst → docs/api/source/avocado_i2n.vmnet.tunnel.rst
diff --git a/doc/api/source/modules.rst → docs/api/source/modules.rst b/doc/api/source/modules.rst → docs/api/source/modules.rst
diff --git a/doc/test_traversal_algorithm.odp → docs/test_traversal_algorithm.odp b/doc/test_traversal_algorithm.odp → docs/test_traversal_algorithm.odp
diff --git a/doc/test_traversal_algorithm.pdf → docs/test_traversal_algorithm.pdf b/doc/test_traversal_algorithm.pdf → docs/test_traversal_algorithm.pdf