rpms/leapp
6
0
Fork 0
Code Issues Pull Requests Releases Activity
e177ea78a8
leapp/SOURCES/0002-docs-Update-docs-engine-and-dependencies.patch
eabdullin e177ea78a8 Import from CS git
2024-11-25 09:10:02 +00:00

510 lines
31 KiB
Diff
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

From 7565b5c8cd5a098522565ff0ed5278eb2b04b7a8 Mon Sep 17 00:00:00 2001
From: Matej Matuska <mmatuska@redhat.com>
Date: Mon, 4 Mar 2024 13:49:18 +0100
Subject: [PATCH 2/6] 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 5b892d8..f78af83 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 8750d07..709c35b 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 46aedbc..7951290 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 4b1b4bc..d8551f4 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -25,8 +25,6 @@ sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(os.path.dirna
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 @@ from recommonmark.transform import AutoStructify # noqa
# 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 @@ templates_path = ['_templates']
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 @@ release = leapp.FULL_VERSION
#
# 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 @@ texinfo_documents = [
'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 b01d156..b1e222e 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 65cc18a..142d884 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 <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 ======================================================
diff --git a/docs/source/devenv-install.md b/docs/source/devenv-install.md
index 84a5bab..210e48f 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 391b37f..d863fab 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 2cc72f3..32b371f 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 37bef8f..243972f 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 <span style="font-size:0.5em; font-weight:normal">(till the next release + 6months)</span>
diff --git a/docs/source/el7toel8/envars.md b/docs/source/el7toel8/envars.md
index 86190ad..6eeb81f 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 a31208f..c2c592f 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 66de4e0..4e00583 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 73b76c1..f1f5636 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 42a823f..b1754dc 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 52310e1..f721d55 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 a0662c5..e63b5e1 100644
--- a/leapp/libraries/actor/__init__.py
+++ b/leapp/libraries/actor/__init__.py
@@ -5,7 +5,7 @@ are placed in the actor's libraries folder.
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 d14c19e..a983cfa 100644
--- a/leapp/libraries/common/__init__.py
+++ b/leapp/libraries/common/__init__.py
@@ -4,7 +4,7 @@ are placed in the repository's libraries folder.
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 68a5f38..1f5dde1 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 54d5ba1..93096c4 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
--
2.47.0
Reference in New Issue View Git Blame Copy Permalink