From 17ee105cfbfb76bc66e29029bb7c5d50270a433a Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Sat, 23 Dec 2023 08:55:59 -0500 Subject: [PATCH 01/13] Docs: bump copyright date Signed-off-by: Cleber Rosa --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 96b16a5f53..1cf3421ccd 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -217,7 +217,7 @@ def generate_vmimage_distro(): master_doc = "index" # pylint: disable=C0103 project = "Avocado" # pylint: disable=C0103 -copyright = "2014-2019, Red Hat" # pylint: disable=W0622,C0103 +copyright = "2014-2023, Red Hat" # pylint: disable=W0622,C0103 VERSION_FILE = os.path.join(ROOT_PATH, "VERSION") VERSION = genio.read_file(VERSION_FILE).strip() From 65b0961f33a53bf0a8aa489160f766b068213e3c Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Sat, 23 Dec 2023 09:16:04 -0500 Subject: [PATCH 02/13] Docs: use the rtd theme also on readthedocs.org It looks like readthedocs.org no longer overrides the theme when it's building the docs. Let's always try to se the rtd theme, unless it's not available, that includes on readthedocs.org (where it should always be available). Signed-off-by: Cleber Rosa --- .readthedocs.yaml | 1 + docs/source/conf.py | 15 ++------------- requirements-doc.txt | 1 + 3 files changed, 4 insertions(+), 13 deletions(-) create mode 100644 requirements-doc.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 519e466fd1..89f5abad74 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -20,5 +20,6 @@ sphinx: # https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html python: install: + - requirements: requirements-doc.txt - method: pip path: . diff --git a/docs/source/conf.py b/docs/source/conf.py index 1cf3421ccd..b1c126a1a4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -19,9 +19,6 @@ sys.path.insert(0, ROOT_PATH) -# Flag that tells if the docs are being built on readthedocs.org -ON_RTD = os.environ.get("READTHEDOCS", None) == "True" - # # Auto generate API documentation # @@ -213,6 +210,7 @@ def generate_vmimage_distro(): "sphinx.ext.intersphinx", "sphinx.ext.todo", "sphinx.ext.coverage", + "sphinx_rtd_theme", ] master_doc = "index" # pylint: disable=C0103 @@ -224,16 +222,7 @@ def generate_vmimage_distro(): version = VERSION # pylint: disable=C0103 release = VERSION # pylint: disable=C0103 -if not ON_RTD: # only import and set the theme if we're building docs locally - try: - import sphinx_rtd_theme - - html_theme = "sphinx_rtd_theme" # pylint: disable=C0103 - html_theme_path = [ - sphinx_rtd_theme.get_html_theme_path() - ] # pylint: disable=C0103 - except ImportError: - html_theme = "default" # pylint: disable=C0103 +html_theme = "sphinx_rtd_theme" # pylint: disable=C0103 htmlhelp_basename = "avocadodoc" # pylint: disable=C0103 diff --git a/requirements-doc.txt b/requirements-doc.txt new file mode 100644 index 0000000000..59709ec721 --- /dev/null +++ b/requirements-doc.txt @@ -0,0 +1 @@ +sphinx-rtd-theme==2.0.0 From c38a5f7cce1e58d706a5a427c3f338ae7a1c840b Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Fri, 22 Dec 2023 09:24:37 -0500 Subject: [PATCH 03/13] Docs/Contributor: do not adverstise contribution through the mailing list Signed-off-by: Cleber Rosa --- docs/source/guides/contributor/chapters/how.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/source/guides/contributor/chapters/how.rst b/docs/source/guides/contributor/chapters/how.rst index 1ca0ff595d..09b05f3aa8 100644 --- a/docs/source/guides/contributor/chapters/how.rst +++ b/docs/source/guides/contributor/chapters/how.rst @@ -51,14 +51,6 @@ Every Pull Request you send will be automatically tested by the `CI system `_ and review will take place in the Pull Request as well. -For people who don’t like the GitHub development model, there is an option to -send the patches to the Mailing List, following a more traditional workflow in -Open Source development communities. The patches are reviewed in the Mailing -List, should you opt for that. Then a maintainer will collect the patches, -integrate them on a branch, and submit it as a GitHub Pull Request. This -process ensures that every contributed patch goes through the CI jobs before -being considered suitable for inclusion. - Remember that we do have a small “Feature Freeze” period right before the release day (usually no longer than one week). It means that during this time, no new feature can be merged into the master branch. From 4ecef770d744bfa841b1f4fb60a99d04f5f34d8c Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Fri, 22 Dec 2023 10:02:19 -0500 Subject: [PATCH 04/13] Docs: treat warning as errors on local builds too Signed-off-by: Cleber Rosa --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index baef078a14..ab2c20d1bf 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,7 +5,7 @@ PYTHON=$(shell which python3 2>/dev/null || which python 2>/dev/null) endif # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = -W SPHINXBUILD = $(PYTHON) -m sphinx PAPER = BUILDDIR = build From ef7a840855e8604d012a3c87d82749584ccf51a2 Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Fri, 22 Dec 2023 10:47:12 -0500 Subject: [PATCH 05/13] Docs/Contributor: add section on contributing docs Contributing docs is not that different from other contributions, but let's add the missing bits. Signed-off-by: Cleber Rosa --- .../contributor/chapters/environment.rst | 3 +++ .../source/guides/contributor/chapters/how.rst | 18 +++++++++++++++++- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/source/guides/contributor/chapters/environment.rst b/docs/source/guides/contributor/chapters/environment.rst index 4aa84d159e..d43c2c0524 100644 --- a/docs/source/guides/contributor/chapters/environment.rst +++ b/docs/source/guides/contributor/chapters/environment.rst @@ -20,6 +20,9 @@ Or if you already have pip installed, you can run directly:: $ pip install -r requirements-dev.txt +If you intend to build the documentation locally, please also run:: + + $ pip install -r requirements-doc.txt Installing in develop mode -------------------------- diff --git a/docs/source/guides/contributor/chapters/how.rst b/docs/source/guides/contributor/chapters/how.rst index 09b05f3aa8..93feece2cf 100644 --- a/docs/source/guides/contributor/chapters/how.rst +++ b/docs/source/guides/contributor/chapters/how.rst @@ -229,4 +229,20 @@ List of known community and third party maintained repositories: Documentation ------------- -.. warning:: TODO: Create how to contribute with documentation. +The process of contributing documentation is very similar to the +process of contributing code. The only noteworthy difference is that +instead of running ``make check`` to verify the soundness of the +changes, you should build the documentation with a command such as:: + +$ make -C docs html + +If there are any warnings or errors introduced by your changes, the +documentation will fail to build, showing the cause, such as in:: + + Warning, treated as error: + $HOME/avocado/docs/source/guides/contributor/chapters/how.rst:239:Unknown directive type "foo". + + .. foo:: bar + make: *** [Makefile:48: html] Error 2 + +A similar check is also performed by the CI, via readthedocs.org. From e0f607a6aae7fd8a1c2a265628bd04e9e0d323c6 Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Fri, 22 Dec 2023 13:43:29 -0500 Subject: [PATCH 06/13] Docs/Contributor: add a section on using a container for development Signed-off-by: Cleber Rosa --- .../contributor/chapters/environment.rst | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/source/guides/contributor/chapters/environment.rst b/docs/source/guides/contributor/chapters/environment.rst index d43c2c0524..545826695e 100644 --- a/docs/source/guides/contributor/chapters/environment.rst +++ b/docs/source/guides/contributor/chapters/environment.rst @@ -5,6 +5,30 @@ Development environment .. warning:: TODO: Needs improvement here. i.e: virtualenvs, GPG, etc. +Using a container +----------------- + +Having reproducible development environments is hard because +developers will usually choose their preferred environments, and those +will never be the same for two people. Using a container can be a +good option if you're unsure whether your development environment is +sound or compatible enough. + +The Avocado project maintains a container image that can serve as a +pretty good starting point for development too (it's actually intended +to be used on some CI checks, but don't mind that). You can pull the +image from:: + + quay.io/avocado-framework/avocado-ci-fedora-38 + +It's a simple image, with just a number of known needed packages +installed. This is the full definition of the image: + +.. literalinclude:: ../../../../../contrib/containers/ci/selftests/fedora-38.docker + +You can use the information there to apply to your own environment if +you choose not to use the container image itself. + Installing dependencies ----------------------- From 0b05704b19372a254db806f592aa4e6970471dc1 Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Fri, 22 Dec 2023 13:48:39 -0500 Subject: [PATCH 07/13] Docs: remove nagging for help All of the Avocado project (and pretty much every single Open Source project) needs help. It feels pointless to me to have this on a couple of locations in the docs. Let's keep track of known documentation related tasks along with all the other known issues (GH Issues). Signed-off-by: Cleber Rosa --- docs/source/.include/helpus.rst | 2 -- docs/source/guides/contributor/chapters/environment.rst | 2 -- docs/source/guides/user/chapters/concepts.rst | 2 -- 3 files changed, 6 deletions(-) delete mode 100644 docs/source/.include/helpus.rst diff --git a/docs/source/.include/helpus.rst b/docs/source/.include/helpus.rst deleted file mode 100644 index 72ebbda447..0000000000 --- a/docs/source/.include/helpus.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. attention:: TODO: This section needs attention! Please, help us contributing - to this document. diff --git a/docs/source/guides/contributor/chapters/environment.rst b/docs/source/guides/contributor/chapters/environment.rst index 545826695e..6debc0b4ca 100644 --- a/docs/source/guides/contributor/chapters/environment.rst +++ b/docs/source/guides/contributor/chapters/environment.rst @@ -1,8 +1,6 @@ Development environment ======================= -.. include:: /.include/helpus.rst - .. warning:: TODO: Needs improvement here. i.e: virtualenvs, GPG, etc. Using a container diff --git a/docs/source/guides/user/chapters/concepts.rst b/docs/source/guides/user/chapters/concepts.rst index a52dc8e99b..540cb4ecf2 100644 --- a/docs/source/guides/user/chapters/concepts.rst +++ b/docs/source/guides/user/chapters/concepts.rst @@ -1,8 +1,6 @@ Basic Concepts ============== -.. include:: /.include/helpus.rst - It is important to understand some basic concepts before start using Avocado. From be8fa4ca266b45453ec5ef034b6eb4d1bde13e6f Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Fri, 22 Dec 2023 14:02:35 -0500 Subject: [PATCH 08/13] Docs/Contributor: update info on GPG signatures The information on setting up the GPG environment is outdated and pretty much all in the "style guide" chapter. Let's update it and organize it better between "setting up" (environment) and using it (style guide). Signed-off-by: Cleber Rosa --- .../contributor/chapters/environment.rst | 27 +++++++++++++- .../contributor/chapters/styleguides.rst | 37 ++++--------------- 2 files changed, 33 insertions(+), 31 deletions(-) diff --git a/docs/source/guides/contributor/chapters/environment.rst b/docs/source/guides/contributor/chapters/environment.rst index 6debc0b4ca..ac81ad86f4 100644 --- a/docs/source/guides/contributor/chapters/environment.rst +++ b/docs/source/guides/contributor/chapters/environment.rst @@ -1,8 +1,6 @@ Development environment ======================= -.. warning:: TODO: Needs improvement here. i.e: virtualenvs, GPG, etc. - Using a container ----------------- @@ -89,3 +87,28 @@ variable ``$AVOCADO_EXTERNAL_PLUGINS_PATH``. The workflow could be:: $ make develop-external You should see the process and status of each directory. + +GPG Signatures +-------------- + +This is an optional step for most contributors, but if you're +interested in ensuring that your contribution is linked to yourself, +this is the best way to do so. + +To get a GPG signature, you can find many howtos on the internet, but +it generally works like this:: + + $ gpg --gen-key # defaults are usually fine (using expiration is recommended) + $ gpg --send-keys $YOUR_KEY # to propagate the key to outer world + +Then, you should enable it in git:: + + $ git config --global user.signingkey $YOUR_KEY + +Optionally, you can link the key with your GH account: + +1. Login to github +2. Go to settings->SSH and GPG keys +3. Add New GPG key +4. run ``$(gpg -a --export $YOUR_EMAIL)`` in shell to see your key +5. paste the key there diff --git a/docs/source/guides/contributor/chapters/styleguides.rst b/docs/source/guides/contributor/chapters/styleguides.rst index 92b10087cf..11ff1c6e14 100644 --- a/docs/source/guides/contributor/chapters/styleguides.rst +++ b/docs/source/guides/contributor/chapters/styleguides.rst @@ -19,41 +19,20 @@ motivation, approach and effects:: Signing commits ~~~~~~~~~~~~~~~ -Optionally you can sign the commits using GPG signatures. Doing -it is simple and it helps from unauthorized code being merged without notice. +If you've set a GPG signature, it's a good idea to put it in use when +committing your changes. To sign your commits, add the ``-S`` command +line option, such as in:: -All you need is a valid GPG signature, git configuration, and slightly modified -workflow to use the signature. Eventually, set it up in GitHub; hence, benefiting -from the “nice” UI. - -Get a GPG signature:: - - # Google for howto, but generally it works like this - $ gpg --gen-key # defaults are usually fine (using expiration is recommended) - $ gpg --send-keys $YOUR_KEY # to propagate the key to outer world - -Enable it in git:: - - $ git config --global user.signingkey $YOUR_KEY - -(optional) Link the key with your GH account:: - - 1. Login to github - 2. Go to settings->SSH and GPG keys - 3. Add New GPG key - 4. run $(gpg -a --export $YOUR_EMAIL) in shell to see your key - 5. paste the key there + $ git commit -S -Use it:: +And if you are merging branches:: - # You can sign commits by using '-S' - $ git commit -S - # You can sign merges by using '-S' $ git merge -S .. warning:: - You can not use the merge button on GitHub to do signed merges as GitHub - does not have your private key. + If you use the merge button on GitHub, the signature will be + performed with GitHub's own private key. Please check whether you + find that acceptable or not. Code style guide ---------------- From 1c66620bcc97e905328dd1efbfc3c244cda55fd6 Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Fri, 22 Dec 2023 14:17:26 -0500 Subject: [PATCH 09/13] Docs/Contributor: update information on code style checker Avocado uses Black for code style enforcement, so the contributor should really refer to it for any information on the topic. Signed-off-by: Cleber Rosa --- docs/source/guides/contributor/chapters/styleguides.rst | 7 ++++++- docs/source/quickstart/index.rst | 4 ++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/source/guides/contributor/chapters/styleguides.rst b/docs/source/guides/contributor/chapters/styleguides.rst index 11ff1c6e14..4e0b0fa57a 100644 --- a/docs/source/guides/contributor/chapters/styleguides.rst +++ b/docs/source/guides/contributor/chapters/styleguides.rst @@ -37,4 +37,9 @@ And if you are merging branches:: Code style guide ---------------- -.. warning:: TODO: Add the Code Style Guide. +Avocado uses the Black code style checker, and thus, you should follow +its very opinionated style. In reality, it's recommended to use your +editor or IDE features to make sure the style is applied +automatically. Please refer to the `black documentation +`__ for more +information. diff --git a/docs/source/quickstart/index.rst b/docs/source/quickstart/index.rst index 645602ff93..01aeca0661 100644 --- a/docs/source/quickstart/index.rst +++ b/docs/source/quickstart/index.rst @@ -269,6 +269,10 @@ Build and Quality Status :target: https://avocado-framework.readthedocs.io/en/latest/ :alt: Documentation Status +.. image:: https://img.shields.io/badge/code%20style-black-000000.svg + :target: https://github.com/psf/black + :alt: Code Style checking by Black + .. _Avocado User's Guide: https://avocado-framework.readthedocs.io/en/latest/guides/user/index.html .. _Installing section on Avocado User’s Guide: https://avocado-framework.readthedocs.io/en/latest/guides/user/chapters/installing.html#installing From 1ee1a41eb6f5a6099d10b2544308ad5d9a16328a Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Fri, 22 Dec 2023 14:30:27 -0500 Subject: [PATCH 10/13] Docs/Contributor: fix reference to ReferenceResolutionResult.CORRUPT And while at it, let's shorten the lengths of the lines around it. Signed-off-by: Cleber Rosa --- docs/source/guides/contributor/chapters/plugins.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/source/guides/contributor/chapters/plugins.rst b/docs/source/guides/contributor/chapters/plugins.rst index 72922d52d4..f52865dcf3 100644 --- a/docs/source/guides/contributor/chapters/plugins.rst +++ b/docs/source/guides/contributor/chapters/plugins.rst @@ -403,10 +403,13 @@ resolve the ``magic:foo`` and ``something-else`` references, but couldn't:: magic something-else Word "something-else" is not a valid magic word ... -We can see that the reference "magic:foo" resembles the magic words by type but it is not magic words ``pass`` or ``fail``. -Consequently, the resolver can provide the user with information about potentially corrupted references. -This can assist the user in identifying typos or reference mistakes. As the creator of the resolver, -you can use the "ReferenceResolutionResult.CORRUPT" variable to notify the user of such a situation. +We can see that the reference "magic:foo" resembles the magic words by +type but it is not magic words ``pass`` or ``fail``. Consequently, +the resolver can provide the user with information about potentially +corrupted references. This can assist the user in identifying typos +or reference mistakes. As the creator of the resolver, you can use the +:data:`avocado.core.resolver.ReferenceResolutionResult.CORRUPT` variable +to notify the user of such a situation. Running magic tests ------------------- From 4ea56fb65dd942e599c0dfcd1c03ad6968a7414c Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Fri, 22 Dec 2023 14:38:12 -0500 Subject: [PATCH 11/13] Docs/Contributor: fix reference to plugin section Signed-off-by: Cleber Rosa --- docs/source/guides/contributor/chapters/results.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source/guides/contributor/chapters/results.rst b/docs/source/guides/contributor/chapters/results.rst index ec99552280..50cfea11d7 100644 --- a/docs/source/guides/contributor/chapters/results.rst +++ b/docs/source/guides/contributor/chapters/results.rst @@ -17,5 +17,6 @@ one to look at. It will require you to implement the methods that will perform actions (write to a file/stream) for each of the defined events on a Job and test execution. -You can take a look at `Plugins` for more information on how to -write a plugin that will activate and execute the new result format. +You can take a look at :ref:`writing_plugin` for more information on +how to write a plugin that will activate and execute the new result +format. From 141ddc8166d74baf220bf7987a6d7b1e6fc04df0 Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Fri, 22 Dec 2023 14:40:51 -0500 Subject: [PATCH 12/13] Docs/Contributor: update info on RFCs Signed-off-by: Cleber Rosa --- docs/source/guides/contributor/chapters/rfc.rst | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/source/guides/contributor/chapters/rfc.rst b/docs/source/guides/contributor/chapters/rfc.rst index d8527f6e38..04c37b9b10 100644 --- a/docs/source/guides/contributor/chapters/rfc.rst +++ b/docs/source/guides/contributor/chapters/rfc.rst @@ -4,12 +4,9 @@ Request for Comments (RFCs) What is a RFC? -------------- -.. warning:: TODO: Better describe our RFC model here. - -Submitting a RFC ----------------- - -.. warning:: TODO: Better describe our RFC model here. +RFCs were the main mechanism used in the early days of the Avocado +project to discuss larger ideas. RFCs have been pretty much +supplanted by BluePrints (see :doc:`/blueprints/BP000`). Previous RFCs ------------- @@ -23,4 +20,3 @@ and discussed on the `Avocado Devel Mailing List`_. ../rfcs/lts .. _Avocado Devel Mailing List: https://www.redhat.com/mailman/listinfo/avocado-devel - From b718763558a2f179cc7098c2841b2a864bb64e5f Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Sat, 23 Dec 2023 15:00:40 -0500 Subject: [PATCH 13/13] Docs: remove no longer active lgtm badges Signed-off-by: Cleber Rosa --- docs/source/quickstart/index.rst | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/docs/source/quickstart/index.rst b/docs/source/quickstart/index.rst index 01aeca0661..612189b6a4 100644 --- a/docs/source/quickstart/index.rst +++ b/docs/source/quickstart/index.rst @@ -249,22 +249,10 @@ Build and Quality Status :target: https://cirrus-ci.com/github/avocado-framework/avocado :alt: Basic checks on Cirrus CI -.. image:: https://img.shields.io/lgtm/alerts/g/avocado-framework/avocado.svg?logo=lgtm&logoWidth=18 - :target: https://lgtm.com/projects/g/avocado-framework/avocado/alerts/ - :alt: lgtm total alerts - .. image:: https://api.codeclimate.com/v1/badges/03f506164e1d19f95480/maintainability :target: https://codeclimate.com/github/avocado-framework/avocado/maintainability :alt: Code Climate Maintainability -.. image:: https://img.shields.io/lgtm/grade/python/g/avocado-framework/avocado.svg?logo=lgtm&logoWidth=18 - :target: https://lgtm.com/projects/g/avocado-framework/avocado/context:python - :alt: lgtm language grade for Python - -.. image:: https://img.shields.io/lgtm/grade/javascript/g/avocado-framework/avocado.svg?logo=lgtm&logoWidth=18 - :target: https://lgtm.com/projects/g/avocado-framework/avocado/context:javascript - :alt: lgtm language grade for JavaScript - .. image:: https://readthedocs.org/projects/avocado-framework/badge/?version=latest :target: https://avocado-framework.readthedocs.io/en/latest/ :alt: Documentation Status