docs: Update sphinx to 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.

.readthedocs.yaml

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

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

@@ -51,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'
 

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/master/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

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/master/repos/system_upgrade/el7toel8/libraries/reporting.py)
 shared library with the `'inhibitor'` group.
 
@@ -132,7 +132,7 @@ 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/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)
+is scheduled to run in the Leapp upgrade workflow. If some [Report](leapp.reporting.Report)
 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:

docs/source/faq.md

@@ -8,12 +8,12 @@
 - [What do I have to do in order to execute actor I just wrote?](#what-do-i-have-to-do-in-order-to-execute-actor-i-just-wrote)
 - [What should I do if I need to execute multiple actors? Can I somehow ensure the dependencies between them?](#what-should-i-do-if-i-need-to-execute-multiple-actors-can-i-somehow-ensure-the-dependencies-between-them)
 - [How can I specify what run time dependencies will my actor have?](#how-can-i-specify-what-run-time-dependencies-will-my-actor-have)
-- [How can I distinguish between actors that I depend on directly (I need to consume their output) and indirectly (I just need them to be executed as part of the upgrade as I don’t handle the upgrade of that specific piece; think PHP vs. Apache - upgrade of Apache is independent of the upgrade of PHP but it needs to be done to enable its upgrade)?](#how-can-i-distinguish-between-actors-that-i-depend-on-directly-i-need-to-consume-their-output-and-indirectly-i-just-need-them-to-be-executed-as-part-of-the-upgrade-as-i-don-t-handle-the-upgrade-of-that-specific-piece-think-php-vs-apache-upgrade-of-apache-is-independent-of-the-upgrade-of-php-but-it-needs-to-be-done-to-enable-its-upgrade)
+- [How can I distinguish between actors that I depend on directly (I need to consume their output) and indirectly (I just need them to be executed as part of the upgrade as I don’t handle the upgrade of that specific piece; think PHP vs. Apache - upgrade of Apache is independent of the upgrade of PHP but it needs to be done to enable its upgrade)?](#how-can-i-distinguish-between-actors-that-i-depend-on-directly-i-need-to-consume-their-output-and-indirectly-i-just-need-them-to-be-executed-as-part-of-the-upgrade-as-i-dont-handle-the-upgrade-of-that-specific-piece)
 - [Once I write an actor that consumes data from some other actors, how can I be sure that the format will not change on the producing side in the future?](#once-i-write-an-actor-that-consumes-data-from-some-other-actors-how-can-i-be-sure-that-the-format-will-not-change-on-the-producing-side-in-the-future)
 - [What are the best practices for writing actors?](#what-are-the-best-practices-for-writing-actors)
 - [What are the requirements for actors to be accepted by upstream?](#what-are-the-requirements-for-actors-to-be-accepted-by-upstream)
 - [How can I debug my actor? Is there a standard/supported way how to log and get logs from actors/channels?](#what-are-the-requirements-for-actors-to-be-accepted-by-upstream)
-- [Are there some technical limitations for an actor? E.g. maximum time execution, size of the input/output, libraries I can use… In case there are, is it possible to specify that the actor needs e.g. longer time for execution?](#are-there-some-technical-limitations-for-an-actor-e-g-maximum-time-execution-size-of-the-input-output-libraries-i-can-use-in-case-there-are-is-it-possible-to-specify-that-the-actor-needs-e-g-longer-time-for-execution)
+- [Are there some technical limitations for an actor? E.g. maximum time execution, size of the input/output, libraries I can use… In case there are, is it possible to specify that the actor needs e.g. longer time for execution?](#are-there-some-technical-limitations-for-an-actor-eg-maximum-time-execution-size-of-the-inputoutput-libraries-i-can-use-in-case-there-are-is-it-possible-to-specify-that-the-actor-needs-eg-longer-time-for-execution)
 - [Are there some actions that are either forbidden or not recommended to be done in actors?](#are-there-some-actions-that-are-either-forbidden-or-not-recommended-to-be-done-in-actors)
 - [I got an error about PES data/ Repositories mapping where I find such files?](#i-got-an-error-about-pes-data-repositories-mapping-where-i-find-such-files)
 
@@ -49,19 +49,21 @@ Source: [How to create a Leapp actor for RHEL 7 to 8 upgrade](el7toel8/actor-rhe
 ## What should I do if I need to execute multiple actors? Can I somehow ensure the dependencies between them?
 
 To be sure that your ActorA runs before your ActorB, produce a specific message in ActorA and let ActorB consume it. By doing this you create a dependency of ActorB on ActorA.
-To run just your actors during development, use snactor run --save-output ActorA to save the message of ActorA to the Leapp repository database and then snactor run ActorB. This way, the ActorB will be able to consume the ActorA's saved message. Read more about that in the [tutorial about messaging](messaging).
+To run just your actors during development, use snactor run --save-output ActorA to save the message of ActorA to the Leapp repository database and then snactor run ActorB. This way, the ActorB will be able to consume the ActorA's saved message. Read more about that in the [tutorial about messaging](messaging.md).
 
 ## How can I specify what run time dependencies will my actor have?
 
-See the section about dependencies in the [Best practices document](best-practices.html#do-not-introduce-new-dependencies)
+See the section about dependencies in the [Best practices document](best-practices.md#do-not-introduce-new-dependencies)
 
-## How can I distinguish between actors that I depend on directly (I need to consume their output) and indirectly (I just need them to be executed as part of the upgrade as I don't handle the upgrade of that specific piece; think PHP vs. Apache - upgrade of Apache is independent of the upgrade of PHP but it needs to be done to enable its upgrade)?
+## How can I distinguish between actors that I depend on directly (I need to consume their output) and indirectly (I just need them to be executed as part of the upgrade as I don't handle the upgrade of that specific piece)?
+
+An example of this is PHP vs. Apache - upgrade of Apache is independent of the upgrade of PHP but it needs to be done to enable its upgrade.
 
 In the case of actors you depend on directly because you consume their message, you don't need to do anything extra, the Leapp framework will make sure that the actors that produce the messages you consume are executed before your actor.
 In case of the actors you depend on indirectly you may approach it in various ways:
 
 - Talk to the developers of the actors you depend on indirectly and agree on sending a message between their actors and your actor. This will cause a direct dependency described above.
-- Talk to the [Engineering Lead](contributing.html#contact) of the OS and Application Modernization group and tell them to coordinate development, testing and release of your actor and the actors you depend on indirectly, targeting the same milestone.
+- Talk to the [Engineering Lead](contributing.md#contact) of the OS and Application Modernization group and tell them to coordinate development, testing and release of your actor and the actors you depend on indirectly, targeting the same milestone.
 
 ## Once I write an actor that consumes data from some other actors, how can I be sure that the format will not change on the producing side in the future?
 
@@ -85,7 +87,7 @@ Source: [How to create a Leapp actor for RHEL 7 to 8 upgrade](el7toel8/actor-rhe
 There are no technical limitations but rather conceptual:
 
 - Libraries to use:
-  - See the section about actor dependencies in the [Best practices document](best-practices.html#do-not-introduce-new-dependencies)
+  - See the section about actor dependencies in the [Best practices document](best-practices.md#do-not-introduce-new-dependencies)
 
 Execution time:
 

docs/source/messaging.md

@@ -1,7 +1,7 @@
 ## Using messaging to send data between actors
 
 The Leapp framework uses messages to send data to other actors that are executed afterward.
-Messages are defined through the models declared [earlier](first-actor.html#creating-a-model). Actors can consume these messages and produce data based on their input.
+Messages are defined through the models declared [earlier](first-actor.md#creating-a-model). Actors can consume these messages and produce data based on their input.
 
 As an example, the actors consume Hostname messages, resolve IPs for those
 hostnames, and create the ResolvedHostname model to send a new type of message.