From 964edced14401b3e29cb5c3afb27b268fcc67e7e Mon Sep 17 00:00:00 2001 From: Matej Matuska Date: Mon, 4 Mar 2024 13:49:18 +0100 Subject: [PATCH] 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 | 2 +- docs/Makefile | 5 ++-- docs/source/best-practices.md | 18 +++++------ docs/source/conf.py | 30 +++++++++---------- docs/source/debugging.md | 2 +- docs/source/deprecation.md | 7 ++--- docs/source/devenv-install.md | 2 +- docs/source/dialogs.md | 4 +-- docs/source/el7toel8/actor-rhel7-to-rhel8.md | 2 +- docs/source/el7toel8/deprecation.md | 2 +- docs/source/el7toel8/envars.md | 2 +- .../source/el7toel8/inhibit-rhel7-to-rhel8.md | 8 +++-- docs/source/faq.md | 16 +++++----- docs/source/messaging.md | 2 +- docs/source/terminology.md | 2 +- docs/source/unit-testing.md | 4 +-- leapp/libraries/actor/__init__.py | 2 +- leapp/libraries/common/__init__.py | 2 +- leapp/utils/__init__.py | 4 +-- requirements-docs.txt | 10 ++++--- 20 files changed, 64 insertions(+), 62 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 5b892d82f..f78af8357 100644 --- a/.readthedocs.yaml +++ b/.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" diff --git a/docs/Makefile b/docs/Makefile index 8750d075a..709c35b80 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/source/best-practices.md b/docs/source/best-practices.md index 46aedbc54..7951290f7 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 4b1b4bc57..d8551f42c 100644 --- a/docs/source/conf.py +++ b/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') 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 65cc18ae3..142d884fb 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/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 (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 @@ -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 ====================================================== diff --git a/docs/source/devenv-install.md b/docs/source/devenv-install.md index 84a5babeb..210e48f4e 100644 --- a/docs/source/devenv-install.md +++ b/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] 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 2cc72f391..32b371f74 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 a31208f32..c2c592fdc 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/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: 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/terminology.md b/docs/source/terminology.md index 42a823faf..b1754dc58 100644 --- a/docs/source/terminology.md +++ b/docs/source/terminology.md @@ -1,4 +1,4 @@ -## Terminology +# Terminology ### Actor diff --git a/docs/source/unit-testing.md b/docs/source/unit-testing.md index 52310e1b8..f721d5553 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/libraries/actor/__init__.py b/leapp/libraries/actor/__init__.py index a0662c50f..e63b5e177 100644 --- a/leapp/libraries/actor/__init__.py +++ b/leapp/libraries/actor/__init__.py @@ -5,7 +5,7 @@ Example: If you actor has a libraries folder with a module.py python module, import it - from the actor like this:: + from the actor like this: from leapp.libraries.actor import module diff --git a/leapp/libraries/common/__init__.py b/leapp/libraries/common/__init__.py index d14c19e5c..a983cfaf0 100644 --- a/leapp/libraries/common/__init__.py +++ b/leapp/libraries/common/__init__.py @@ -4,7 +4,7 @@ Example: If any of the repositories has a libraries folder with a module.py python module, import it - from the actor like this:: + from the actor like this: from leapp.libraries.common import module 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 54d5ba1b4..93096c425 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,7 +1,9 @@ -r requirements-tests.txt -CommonMark==0.7.5 -sphinx>=1.5,<1.6 -sphinx_rtd_theme==0.4.3 +sphinx==7.2.6 +sphinx_rtd_theme +sphinxcontrib-jquery +docutils +CommonMark +myst-parser sphinx-autobuild -git+https://github.com/leapp-to/recommonmark.git@master