Merge pull request #5840 from clebergnu/contributor_guide_review

Signed-off-by: Jan Richter <[email protected]>
avocado-framework · Dec 25, 2023 · 835dd78 · 835dd78
2 parents 09fd209 + b718763
commit 835dd78
Show file tree

Hide file tree

Showing 13 changed files with 104 additions and 85 deletions.
diff --git 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/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

diff --git a/docs/source/.include/helpus.rst b/docs/source/.include/helpus.rst
diff --git 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,27 +210,19 @@ def generate_vmimage_distro():
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx.ext.coverage",
+    "sphinx_rtd_theme",
 ]
 
 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()
 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/docs/source/guides/contributor/chapters/environment.rst b/docs/source/guides/contributor/chapters/environment.rst
@@ -1,9 +1,29 @@
 Development environment
 =======================
 
-.. include:: /.include/helpus.rst
+Using a container
+-----------------
 
-.. warning:: TODO: Needs improvement here. i.e: virtualenvs, GPG, etc.
+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
 -----------------------
@@ -20,6 +40,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
 --------------------------
@@ -64,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/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 <https://github.com/avocado-framework/avocado/actions>`_ 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.
@@ -237,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.
diff --git 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
 -------------------

diff --git 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.
diff --git 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
-
diff --git a/docs/source/guides/contributor/chapters/styleguides.rst b/docs/source/guides/contributor/chapters/styleguides.rst
@@ -19,43 +19,27 @@ 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
 ----------------
 
-.. 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
+<https://black.readthedocs.io/en/stable/index.html>`__ for more
+information.
diff --git 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.
 
 

diff --git a/docs/source/quickstart/index.rst b/docs/source/quickstart/index.rst
@@ -249,26 +249,18 @@ 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
 
+.. 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

diff --git a/requirements-doc.txt b/requirements-doc.txt
@@ -0,0 +1 @@
+sphinx-rtd-theme==2.0.0