Add code documentation generated from docstrings

.gitignore

@@ -1,6 +1,7 @@
 # tmt-specific
 
 /tmp/
+docs/autodocs/*.rst
 docs/_build
 docs/spec
 docs/stories

docs/Makefile

@@ -16,10 +16,10 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help generate-stories clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+.PHONY: help generate-stories generate-autodocs clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
 
 clean:
-	rm -rf $(BUILDDIR) stories spec
+	rm -rf $(BUILDDIR) stories spec autodocs/*.rst
 
 ##
 ## Building documentation
@@ -52,7 +52,7 @@ REPODIR       = ..
 TMTDIR        = $(REPODIR)/tmt
 SCRIPTSDIR    = scripts
 
-generate: spec stories generate-lint-checks generate-stories  ## Refresh all generated documentation sources
+generate: spec stories generate-lint-checks generate-stories generate-autodocs  ## Refresh all generated documentation sources
 
 spec:
 	mkdir -p spec
@@ -68,6 +68,9 @@ generate-lint-checks: spec spec/lint.rst  ## Generate documentation sources for
 generate-stories: stories  ## Generate documentation sources for stories
 	$(SCRIPTSDIR)/generate-stories.py story.rst.j2
 
+generate-autodocs:  ## Generate autodocs from source docstrings
+	cd ../ && sphinx-apidoc --force --implicit-namespaces --no-toc -o docs/autodocs tmt
+
 ##
 ## Help!
 ##

docs/classes.rst

@@ -1,8 +1,8 @@
 .. _classes:
 
-===============
-    Classes
-===============
+======================
+    Class Overview
+======================
 
 
 Class Structure
@@ -456,11 +456,3 @@ would do, but it makes it explicit and involves correct type conversion:
     >>> command = script.to_shell_command()
     >>> str(command)
     "/bin/bash -c '\ncd $HOME\nls -al\n'"
-
-
-Essential Classes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. automodule:: tmt
-    :members:
-    :undoc-members:

docs/code.rst

@@ -0,0 +1,23 @@
+
+==================
+    Code
+==================
+
+In order to get a quick start with the ``tmt`` source code you
+might want look through the :ref:`classes` first to learn about
+the overall structure of the code. The :ref:`plugins` can help if
+you are planning to write a new plugin. To find detailed
+information about individual classes, modules and packages inspect
+the documentation generated from sources linked below.
+
+.. toctree::
+    :maxdepth: 2
+
+    Class Overview <classes>
+    Plugin Introduction <plugins>
+    tmt <autodocs/tmt>
+
+.. toctree::
+    :maxdepth: 3
+
+    tmt.steps <autodocs/tmt.steps>

docs/conf.py

@@ -102,6 +102,7 @@ def _load_theme(
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autodoc.typehints',
     'sphinx_rtd_theme',
     ]
 
@@ -178,6 +179,18 @@ def _load_theme(
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# Autodocs & type hints
+autodoc_default_flags = ['members', 'undoc-members', 'show-inheritance', 'private-members']
+autodoc_default_options = {
+    # Enable to "ignore" re-imported names in `tmt.__all__`
+    'ignore-module-all': True
+    }
+autoclass_content = "both"
+
+autodoc_typehints_format = 'short'
+autodoc_typehints_description_target = 'all'
+# This one works, but it's a bit uglier than the default value (`signature`).
+# autodoc_typehints = 'description'
 
 # -- Options for HTML output ----------------------------------------------
 

docs/index.rst

@@ -33,6 +33,5 @@ Table of Contents
     Stories <stories>
     Questions <questions>
     Contribute <contribute>
-    Classes <classes>
-    Plugins <plugins>
+    Code <code>
     Releases <releases>

docs/plugins.rst

@@ -1,8 +1,8 @@
 .. _plugins:
 
-===============
-    Plugins
-===============
+===========================
+    Plugin Introduction
+===========================
 
 Let's have a look at plugins. Each of the six steps defined by
 :ref:`/spec/plans` supports multiple methods. These methods are

plans/install/docs.fmf

@@ -7,6 +7,7 @@ prepare:
     package:
       - make
       - python3-pip
+      - python3-docutils
 execute:
     script: |
         set -ex

tmt/hardware.py

@@ -562,7 +562,7 @@ def expand_name(self) -> ConstraintNameComponents:
         Expand constraint name into its components.
 
         :returns: tuple consisting of constraint name components: name, optional indices, child
-        properties, etc.
+            properties, etc.
         """
 
         match = CONSTRAINT_NAME_PATTERN.match(self.name)

tmt/log.py

@@ -450,7 +450,7 @@ def __init__(
         """
         Create a ``Logger`` instance with given verbosity levels.
 
-        :param actual_logger: a :py:class:`logging.Logger` instance, the _raw logger_
+        :param actual_logger: a :py:class:`logging.Logger` instance, the raw logger
             to use for logging.
         :param base_shift: shift applied to all messages processed by this logger.
         :param labels_padding: if set, rendered labels would be padded to this

tmt/queue.py

@@ -25,7 +25,7 @@ class TaskOutcome(Generic[TaskT]):
     executed, where and what was the result.
     """
 
-    #: A :py:`_Task` instace the outcome relates to.
+    #: A :py:class:`_Task` instace the outcome relates to.
     task: TaskT
 
     #: A logger to use for logging events related to the outcome.
@@ -157,7 +157,7 @@ def go(self) -> Iterator[TaskOutcome['Self']]:
         old_loggers: dict[str, Logger] = {}
 
         with ThreadPoolExecutor(max_workers=len(self.guests)) as executor:
-            futures: dict[Future[None], Guest] = {}
+            futures: dict[Future[None], 'Guest'] = {}
 
             for guest in self.guests:
                 # Swap guest's logger for the one we prepared, with labels

tmt/steps/__init__.py

@@ -74,6 +74,8 @@
 
 TEST_TOPOLOGY_FILENAME_BASE = 'tmt-test-topology'
 
+CODE_BLOCK_REGEXP = re.compile(r"^\s*\.\. code-block::.*$\n", re.MULTILINE)
+
 
 PHASE_OPTIONS = tmt.options.create_options_decorator([
     option(
@@ -964,7 +966,7 @@ def __init__(
 
         self.name = name
         self.class_ = class_
-        self.doc = doc
+        self.doc = CODE_BLOCK_REGEXP.sub("", doc)
         self.order = order
 
         # Parse summary and description from provided doc string
@@ -2052,7 +2054,7 @@ def sync_with_guests(
     needed, and this function handles the details.
 
     :param step: step managing the sync operation.
-    :param action: ``push`` or ``pull`, used for nicer logging.
+    :param action: ``push`` or ``pull``, used for nicer logging.
     :param task: :py:class:`PushTask` or :py:class:`PullTask` which represents
         the actual operation.
     :param logger: logger to use for logging.

tmt/steps/discover/fmf.py

@@ -182,11 +182,15 @@ class DiscoverFmf(tmt.steps.discover.DiscoverPlugin[DiscoverFmfStepData]):
     By default all available tests from the current repository are used
     so the minimal configuration looks like this:
 
+    .. code-block::
+
         discover:
             how: fmf
 
     Full config example:
 
+    .. code-block::
+
         discover:
             how: fmf
             url: https://github.com/teemtee/tmt
@@ -202,11 +206,14 @@ class DiscoverFmf(tmt.steps.discover.DiscoverPlugin[DiscoverFmfStepData]):
     together with 'ref', 'path' and 'url', However 'ref' is not possible
     without using 'url'.
 
+    .. code-block::
+
         discover:
             how: fmf
             dist-git-source: true
 
     Related config options (all optional):
+
     * dist-git-merge - set to True if you want to copy in extracted
       sources to the local repo
     * dist-git-init - set to True and 'fmf init' will be called inside
@@ -221,6 +228,8 @@ class DiscoverFmf(tmt.steps.discover.DiscoverPlugin[DiscoverFmfStepData]):
     expressions are supported for both relation and target part of the
     value. Relation can be omitted to target match any relation.
 
+    .. code-block::
+
         discover:
             how: fmf
             link: verifies:.*issue/850$
@@ -230,12 +239,15 @@ class DiscoverFmf(tmt.steps.discover.DiscoverPlugin[DiscoverFmfStepData]):
     testing changes to tests themselves (e.g. in a pull request CI).
 
     Related config options (all optional):
+
     * modified-only - set to True if you want to filter modified tests
     * modified-url - fetched as "reference" remote in the test dir
     * modified-ref - the ref to compare against
 
     Example to compare local repo against upstream 'main' branch:
 
+    .. code-block::
+
         discover:
             how: fmf
             modified-only: True

tmt/steps/discover/shell.py

@@ -208,39 +208,45 @@ class DiscoverShell(tmt.steps.discover.DiscoverPlugin[DiscoverShellData]):
     in the plan as a list of dictionaries containing test name, actual
     test script and optionally a path to the test. Example config:
 
-    discover:
-        how: shell
-        tests:
-        - name: /help/main
-          test: tmt --help
-        - name: /help/test
-          test: tmt test --help
-        - name: /help/smoke
-          test: ./smoke.sh
-          path: /tests/shell
+    .. code-block:: yaml
+
+        discover:
+            how: shell
+            tests:
+            - name: /help/main
+              test: tmt --help
+            - name: /help/test
+              test: tmt test --help
+            - name: /help/smoke
+              test: ./smoke.sh
+              path: /tests/shell
 
     For DistGit repo one can download sources and use their code.
     They are available in TMT_SOURCE_DIR however no patches are applied.
     By default tarballs are extracted which can be disabled.
 
-    discover:
-        how: shell
-        dist-git-source: true
-        tests:
-        - name: /upstream
-          test: cd $TMT_SOURCE_DIR/*/tests && make test
+    .. code-block:: yaml
+
+        discover:
+            how: shell
+            dist-git-source: true
+            tests:
+            - name: /upstream
+              test: cd $TMT_SOURCE_DIR/*/tests && make test
 
     To clone a remote repository and use it as a source specify `url`.
     It accepts also `ref` to checkout provided reference. Dynamic
     reference feature is supported as well.
 
-    discover:
-        how: shell
-        url: https://github.com/teemtee/tmt.git
-        ref: "1.18.0"
-        tests:
-        - name: first test
-          test: ./script-from-the-repo.sh
+    .. code-block:: yaml
+
+        discover:
+            how: shell
+            url: https://github.com/teemtee/tmt.git
+            ref: "1.18.0"
+            tests:
+            - name: first test
+              test: ./script-from-the-repo.sh
     """
 
     _data_class = DiscoverShellData

tmt/steps/finish/ansible.py

@@ -12,12 +12,16 @@ class FinishAnsible(
 
     Single playbook config:
 
+    .. code-block:: yaml
+
         finish:
             how: ansible
             playbook: ansible/packages.yml
 
     Multiple playbooks config:
 
+    .. code-block:: yaml
+
         finish:
             how: ansible
             playbook:

tmt/steps/finish/shell.py

@@ -44,11 +44,13 @@ class FinishShell(tmt.steps.finish.FinishPlugin[FinishShellData]):
 
     Example config:
 
-    finish:
-        how: shell
-        script:
-            - upload-logs.sh || true
-            - rm -rf /tmp/temporary-files
+    .. code-block:: yaml
+
+        finish:
+            how: shell
+            script:
+              - upload-logs.sh || true
+              - rm -rf /tmp/temporary-files
 
     Use the 'order' attribute to select in which order finishing tasks
     should happen if there are multiple configs. Default order is '50'.

tmt/steps/prepare/ansible.py

@@ -63,12 +63,16 @@ class PrepareAnsible(tmt.steps.prepare.PreparePlugin[PrepareAnsibleData]):
 
     Single playbook config:
 
+    .. code-block:: yaml
+
         prepare:
             how: ansible
             playbook: ansible/packages.yml
 
     Multiple playbooks config:
 
+    .. code-block:: yaml
+
         prepare:
             how: ansible
             playbook:
@@ -80,6 +84,8 @@ class PrepareAnsible(tmt.steps.prepare.PreparePlugin[PrepareAnsibleData]):
     Remote playbooks can be referenced as well as local ones, and both
     kinds can be intermixed:
 
+    .. code-block:: yaml
+
         prepare:
             how: ansible
             playbook: