docs: Update docs engine and dependencies

Changes with version 3.5.4:
- The biggest change is the replacement of recommonmark with MyST for markdown
parsing. The recommonmark library is no longer maintained and is also deprecated
in sphinx. The recommended replacement is MyST library. In our case it seems
like a drop-in replacement with only errors being "non-consecutive header level
increment", which shouldn't be a problem and the docs build successfully.

Changes with version 4.5.0
- No major changes, just some deprecated APIs are replaced.

Changes with version 5.3.0
- Instead of linking to autodoc generated HTML files (in the pydoc dir), use cross
references. Also fix some of the ambiguous references and repair some of
the broken ones.

Changes with version 6.2.1
- No breaking changes.
- This version requires Python 3.10 for deps to correctly install,
otherwise the version of sphinx-autobuild and sphinxcontrib-* packages
would have to pinned.

Changes with version 7.2.6
- No breaking changes.
- Works properly on Python >= 3.10. On Python 3.12 requires manual upgrade
of the six package until the version is bumped in requirements.txt.

.readthedocs.yaml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "2.7"
+    python: "3.10"
     # You can also specify other tool versions:
     # nodejs: "20"
     # rust: "1.70"

docs/Makefile

@@ -15,12 +15,11 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 livehtml:
-	@$(SPHINXAUTOBUILD) -z ../leapp "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(0)
-
-.PHONY: help Makefile
+	@$(SPHINXAUTOBUILD) --watch ../leapp "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(0)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+.PHONY: all help Makefile

docs/source/best-practices.md

@@ -30,10 +30,10 @@ See the [tutorial on basic usage of snactor](first-actor).
 Part of your actor's functionality might end up being rather generic or abstract. In that case, consider converting it
 to a shared library function. You can introduce it in one of these two places:
 
-- The [Leapp Standard Library](pydoc/leapp.libraries.stdlib)
+- The [Leapp Standard Library](leapp.libraries.stdlib)
 
   The most generic functionality which actors of any workflow can use, e.g. function for exectuting a shell command,
-  should go to the [Leapp Standard Library](pydoc/leapp.libraries.stdlib).
+  should go to the [Leapp Standard Library](leapp.libraries.stdlib).
   For that, please submit proposals through issues or pull requests under the
   [leapp GitHub repository](https://github.com/oamg/leapp/).
 
@@ -146,16 +146,16 @@ For more details about dependencies and how to modify them, see the [How to deal
 
 If you encounter unexpected input or any other error during execution of an actor and want to stop it, use these exceptions:
 
-- [StopActorExecution](pydoc/leapp.html#leapp.exceptions.StopActorExecution) - raising this exception is a convenient to stop actor's execution with no side effect - it has the same effect as returning `None` from the main `process()` method in the `actor.py`
-- [StopActorExecutionError](pydoc/leapp.html#leapp.exceptions.StopActorExecutionError) - raising this exception will stop actor's execution and notify the framework that an error has occurred and can influence the result of the workflow execution.
+- [StopActorExecution](leapp.exceptions.StopActorExecution) - raising this exception is a convenient to stop actor's execution with no side effect - it has the same effect as returning `None` from the main `process()` method in the `actor.py`
+- [StopActorExecutionError](leapp.exceptions.StopActorExecutionError) - raising this exception will stop actor's execution and notify the framework that an error has occurred and can influence the result of the workflow execution.
 
-In case of [StopActorExecutionError](pydoc/leapp.html#leapp.exceptions.StopActorExecutionError) the execution of the workflow will stop or not according to the [policy](pydoc/leapp.workflows.html?highlight=FailPhase#module-leapp.workflows.policies) defined in the workflow, there are three possibilities:
+In case of [StopActorExecutionError](leapp.exceptions.StopActorExecutionError) the execution of the workflow will stop or not according to the [policy](leapp.workflows.policies) defined in the workflow, there are three possibilities:
 
-- [FailImmediately](pydoc/leapp.workflows.html?highlight=FailPhase#leapp.workflows.policies.Policies.Errors.FailImmediately) - end the workflow execution right away
-- [FailPhase](pydoc/leapp.workflows.html?highlight=FailPhase#leapp.workflows.policies.Policies.Errors.FailPhase) - end the workflow execution after finishing the current phase
-- [ReportOnly](pydoc/leapp.workflows.html?highlight=FailPhase#leapp.workflows.policies.Policies.Errors.ReportOnly) - do not end the workflow execution at all and continue with logging the issue only
+- [FailImmediately](leapp.workflows.policies.Policies.Errors.FailImmediately) - end the workflow execution right away
+- [FailPhase](leapp.workflows.policies.Policies.Errors.FailPhase) - end the workflow execution after finishing the current phase
+- [ReportOnly](leapp.workflows.policies.Policies.Errors.ReportOnly) - do not end the workflow execution at all and continue with logging the issue only
 
-You can also use the [StopActorExecution](pydoc/leapp.html#leapp.exceptions.StopActorExecution) and [StopActorExecutionError](pydoc/leapp.html#leapp.exceptions.StopActorExecutionError) exceptions inside a private or shared library.
+You can also use the [StopActorExecution](leapp.exceptions.StopActorExecution) and [StopActorExecutionError](leapp.exceptions.StopActorExecutionError) exceptions inside a private or shared library.
 
 ## Use the LEAPP and LEAPP\_DEVEL prefixes for new envars
 

docs/source/conf.py

@@ -25,8 +25,6 @@
 
 import sphinx_rtd_theme  # noqa
 import leapp  # noqa
-from recommonmark.parser import CommonMarkParser  # noqa
-from recommonmark.transform import AutoStructify  # noqa
 
 # -- General configuration ------------------------------------------------
 
@@ -37,9 +35,12 @@
 # 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',
-              'sphinx.ext.githubpages',
-              'autosectionlabelext']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.githubpages',
+    'autosectionlabelext',
+    'myst_parser',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -50,6 +51,9 @@
 source_suffix = ['.md', '.rst']
 # source_suffix = '.rst'
 
+# how many level of headings in markdown should linkable anchors be generated for
+myst_heading_anchors = 3
+
 # The master toctree document.
 master_doc = 'index'
 
@@ -72,7 +76,8 @@
 #
 # 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'
+# highlight_language = "python"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -165,11 +170,6 @@
      'Miscellaneous'),
 ]
 
-
-source_parsers = {
-    '.md': CommonMarkParser,
-}
-
 autoclass_content = 'both'
 autodoc_default_flags = ['members', 'undoc-members', 'inherited-members', 'show-inheritance']
 
@@ -185,9 +185,7 @@ def filter_unwanted_leapp_types(app, what, name, obj, skip, options):
 
 
 def setup(app):
-    app.add_config_value('recommonmark_config', {}, True)
-    app.add_transform(AutoStructify)
     app.connect('autodoc-skip-member', filter_unwanted_leapp_types)
-    app.add_stylesheet('css/asciinema-player.css')
-    app.add_stylesheet('css/custom.css')
-    app.add_javascript('js/asciinema-player.js')
+    app.add_css_file('css/asciinema-player.css')
+    app.add_css_file('css/custom.css')
+    app.add_js_file('js/asciinema-player.js')

docs/source/debugging.md

@@ -4,7 +4,7 @@
 
 The snactor tool is used to debug your actors. You can execute actors
 and save their output, so that it can be consumed by other actors.
-See [Storing messages in the repository data for reuse](messaging.html#storing-messages-in-the-repository-data-for-reuse).
+See [Storing messages in the repository data for reuse](messaging.md#storing-messages-in-the-repository-data-for-reuse).
 
 Snactor checks for the `LEAPP_DEBUG` environment variable and has also
 the --debug parameter which sets the environment variable to '1' when it is

docs/source/deprecation.md

@@ -11,7 +11,7 @@ impact on your code, we introduce the deprecation process described below.
 The following lists cover deprecated functionality in the leapp utility, snactor,
 the leapp standard library, etc. But don't cover deprecated functionalities
 from particular leapp repositories (e.g. the [elt7toel8](https://github.com/oamg/leapp-repository/tree/main/repos/system_upgrade/el7toel8) leapp repository). For
-such information, see [Deprecated functionality in the el7toel8 repository](el7toel8/deprecation.html#deprecated-functionality-in-the-el7toel8-repository).
+such information, see [Deprecated functionality in the el7toel8 repository](el7toel8/deprecation.md#deprecated-functionality-in-the-el7toel8-repository).
 
 ## current upstream development <span style="font-size:0.5em; font-weight:normal">(till the next release + 6months)</span>
 
@@ -106,7 +106,7 @@ the deprecation of derived classes.*
 In case of a class deprecation, all derived classes are considered to be deprecated
 as well. However, the current reporting could be a little bit confusing. To
 improve that, the `stack_level_offset` option can be specified.
-See [examples of the use of the @deprecated decorator for classes](deprecation.html#classes).
+See [examples of the use of the @deprecated decorator for classes](deprecation.md#classes).
 
 When you mark any entity as deprecated and this entity is then used
 in the code, users will be notified about that via a terminal and report
@@ -290,9 +290,8 @@ before the definition of the `produce_answer` function. But if we do the same
 for the test function, we will get an error (see that we have now just one
 deprecation warning now):
 
-```python
+```
 | 21:59:57 | conftest | INFO | conftest.py | Actor 'foo_producer' context teardown complete
-
 repos/system_upgrade/el7toel8/actors/fooproducer/tests/test_unit_fooproducer.py::test_process FAILED
 
 ====================================================== FAILURES ======================================================

docs/source/devenv-install.md

@@ -49,7 +49,7 @@ $ pip install git+https://github.com/oamg/leapp
 ```
 
 Once the framework is installed, you can use the snactor tool.
-```shell
+```
 $ snactor --help
 usage: snactor [-h] [--version] [--logger-config LOGGER_CONFIG]
                [--config CONFIG] [--verbose] [--debug]

docs/source/dialogs.md

@@ -4,9 +4,9 @@ Leapp framework uses dialogs to ask user for any additional information an actor
 automatically.
 Dialogs contain Components which represent individual questions.
 Complete list of component types can be found in
-[documentation](pydoc/leapp.dialogs.html#module-leapp.dialogs.components).
+[documentation](leapp.dialogs.components).
 
-As an example we will change [IpResolver](messaging.html#creating-a-message-consuming-actor) actor in a way that user
+As an example we will change [IpResolver](messaging.md#creating-a-message-consuming-actor) actor in a way that user
 will decide which hostnames will be resolved.
 
 

docs/source/el7toel8/actor-rhel7-to-rhel8.md

@@ -420,7 +420,7 @@ The process of inhibiting the upgrade is done by the VerifyCheckResult actor, ex
 
 ### How to stop execution of my actor in case of an unexpected error?
 
-It’s good practice to code defensively so the code is robust. The actor should detect unexpected input or result of some operation and exit gracefully instead of tracebacking. In case you detect an unexpected behavior, let the framework know about it by raising [StopActorExecutionError](pydoc/leapp.html#leapp.exceptions.StopActorExecutionError). Framework will act based on the [setting of the upgrade workflow](pydoc/leapp.workflows.html?highlight=FailPhase#module-leapp.workflows.policies) in one of the following three ways:
+It’s good practice to code defensively so the code is robust. The actor should detect unexpected input or result of some operation and exit gracefully instead of tracebacking. In case you detect an unexpected behavior, let the framework know about it by raising [StopActorExecutionError](leapp.exceptions.StopActorExecutionError). Framework will act based on the [setting of the upgrade workflow](leapp.workflows.policies) in one of the following three ways:
 
 - end the upgrade process right away, or
 - end the upgrade process after finishing the current phase, or

docs/source/el7toel8/deprecation.md

@@ -8,7 +8,7 @@ after which the related functionality can be removed at any time.
 
 *Note* The lists cover just the functionality provided inside the el7toel8
 repository only. For the functionality deprecated in the leapp
-framework, see [List of deprecated functionality in leapp](../deprecation.html#list-of-deprecated-functionality-in-leapp)
+framework, see [List of deprecated functionality in leapp](../deprecation.md#list-of-the-deprecated-functionality-in-leapp)
 
 ## current upstream development <span style="font-size:0.5em; font-weight:normal">(till the next release + 6months)</span>
 

docs/source/el7toel8/envars.md

@@ -2,7 +2,7 @@
 
 Actors in the el7toel8 repository use environment variables specified below.
 All these envars use the suggested prefixes specified in
-[the best practices document](../best-practices#use-the-leapp-and-leapp-devel-prefixes-for-new-envars)
+[the best practices document](../best-practices.md#use-the-leapp-and-leapp_devel-prefixes-for-new-envars)
 for the leapp project to distinguish their purpose: _production_ or _devel_ use.
 
 If the argument for envars below is not specified, it is expected to set `0`

docs/source/el7toel8/inhibit-rhel7-to-rhel8.md

@@ -5,7 +5,7 @@
 With latest changes on Leapp and with new actors added to the el7toel8 Leapp
 repository, any actor can inhibit the upgrade process by producing a specific
 message when a problem is found. The message model to use in this case is
-[Report](pydoc/leapp.reporting.html#leapp.reporting.Report).
+[Report](leapp.reporting.Report).
 If there is at least one Report message with the `'inhibitor'` group produced before
 the Report phase, the upgrade will be stopped in the Reports phase, in which the
 messages are being collected. It means that any Report message produced
@@ -55,7 +55,7 @@ $ snactor run CheckSystemArch --verbose
 
 If, instead of only adding a message to the log, the actor writer wants to make
 sure that the upgrade process will be stopped in case of unsupported arch, the
-actor needs to produce a [Report](/pydoc/leapp.reporting.html#leapp.reporting.Report)
+actor needs to produce a [Report](leapp.reporting.Report)
 message using one of the `report_*` functions from the [reporting](https://github.com/oamg/leapp-repository/blob/main/repos/system_upgrade/el7toel8/libraries/reporting.py)
 shared library with the `'inhibitor'` group.
 
@@ -131,8 +131,10 @@ This is all that an actor needs to do in order to verify if some condition is
 present on the system and inhibit the upgrade process based on that check.
 
 After all the system checks are executed by different actors, an existing actor
-named [VerifyCheckResults](https://github.com/oamg/leapp-repository/tree/main/repos/system_upgrade/el7toel8/actors/verifycheckresults)
+==== BASE ====
+named [VerifyCheckResults](https://github.com/oamg/leapp-repository/tree/master/repos/system_upgrade/el7toel8/actors/verifycheckresults)
 is scheduled to run in the Leapp upgrade workflow. If some [Report](/pydoc/leapp.reporting.html#leapp.reporting.Report)
+==== BASE ====
 message with the `'inhibitor'` group was generated by some previous execution of
 another actor in any previous phase of the workflow, like the sample one we just
 wrote, the following output will be displayed to the user: