diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 553cd647d..f78af8357 100644 --- a/.readthedocs.yaml +++ b/.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" diff --git a/docs/source/best-practices.md b/docs/source/best-practices.md index f3387e2dd..c4003fb1a 100644 --- a/docs/source/best-practices.md +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index af7f542bd..23eea56d8 100644 --- a/docs/source/conf.py +++ b/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' diff --git a/docs/source/debugging.md b/docs/source/debugging.md index b01d15699..b1e222ec1 100644 --- a/docs/source/debugging.md +++ b/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 diff --git a/docs/source/deprecation.md b/docs/source/deprecation.md index b58375837..f6ede9d47 100644 --- a/docs/source/deprecation.md +++ b/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 (till the next release + 6months) @@ -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 diff --git a/docs/source/dialogs.md b/docs/source/dialogs.md index 391b37f21..d863fabce 100644 --- a/docs/source/dialogs.md +++ b/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. diff --git a/docs/source/el7toel8/actor-rhel7-to-rhel8.md b/docs/source/el7toel8/actor-rhel7-to-rhel8.md index 06bdfae35..1f110e205 100644 --- a/docs/source/el7toel8/actor-rhel7-to-rhel8.md +++ b/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 diff --git a/docs/source/el7toel8/deprecation.md b/docs/source/el7toel8/deprecation.md index 37bef8fcc..243972f86 100644 --- a/docs/source/el7toel8/deprecation.md +++ b/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 (till the next release + 6months) diff --git a/docs/source/el7toel8/envars.md b/docs/source/el7toel8/envars.md index 86190ad72..6eeb81f87 100644 --- a/docs/source/el7toel8/envars.md +++ b/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` diff --git a/docs/source/el7toel8/inhibit-rhel7-to-rhel8.md b/docs/source/el7toel8/inhibit-rhel7-to-rhel8.md index 5e97c78ec..77569c1d3 100644 --- a/docs/source/el7toel8/inhibit-rhel7-to-rhel8.md +++ b/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: diff --git a/docs/source/faq.md b/docs/source/faq.md index 66de4e068..4e00583de 100644 --- a/docs/source/faq.md +++ b/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: diff --git a/docs/source/messaging.md b/docs/source/messaging.md index 73b76c16e..f1f56368c 100644 --- a/docs/source/messaging.md +++ b/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. diff --git a/docs/source/unit-testing.md b/docs/source/unit-testing.md index d4feec998..cf4d73c84 100644 --- a/docs/source/unit-testing.md +++ b/docs/source/unit-testing.md @@ -49,7 +49,7 @@ def test_actor_execution(current_actor_context): current_actor_context.run() ``` -This example makes use of the [current_actor_context](pydoc/leapp.html#leapp.snactor.fixture.current_actor_context) +This example makes use of the [current_actor_context](#leapp.snactor.fixture.current_actor_context) fixture and will execute the `MyActor` actor. Now if you would want to check that it produced an imaginary model called @@ -92,7 +92,7 @@ The unit testing support was first implemented with the help of [pytest fixtures](https://docs.pytest.org/en/latest/fixture.html). Nowadays, we encourage you to use only the `current_actor_context` fixture mentioned above. However the other fixtures have been preserved and are -still possible to use - see their [documentation](pydoc/leapp.html#module-leapp.snactor.fixture). +still possible to use - see their [documentation](#leapp.snactor.fixture). #### Testing actors that modify the OS diff --git a/leapp/utils/__init__.py b/leapp/utils/__init__.py index 68a5f3824..1f5dde1e5 100644 --- a/leapp/utils/__init__.py +++ b/leapp/utils/__init__.py @@ -13,8 +13,8 @@ def get_api_models(actor, what): :param what: A string which either is 'consumes' or 'produces' :type what: str - :param actor: Actor type/instance or ActorDefinition instance to retrieve the information from - :type actor: Actor or ActorDefinition + :param actor: type/instance or ActorDefinition instance to retrieve the information from + :type actor: leapp.actors.Actor or ActorDefinition :return: Tuple of all produced or consumed models as specified by actor and APIs used by the actor. """ diff --git a/requirements-docs.txt b/requirements-docs.txt index f067d1930..9540a5a0a 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -5,5 +5,5 @@ sphinxcontrib-jquery docutils CommonMark myst-parser -sphinx==4.5.0 +sphinx==5.3.0 sphinx-autobuild