docs: Extend contribution parts with DoD hints (#94)

Co-authored-by: Julien THOMAS <external.julien.thomas@de.bosch.com>

docs/conf.py

@@ -49,6 +49,7 @@
     "sphinx.ext.viewcode",
     "sphinxcontrib.programoutput",
     "sphinx_autodoc_typehints",
+    "sphinx.ext.autosectionlabel",
 ]
 
 source_suffix = {

docs/getting_started/contribution_guide.rst

@@ -59,4 +59,129 @@ Kiso-testing and make sure that you understand your rights and obligations.
 Any contributions to Kiso-testing project code base needs to be licensed under
 EPL v2.0.
 
+What should I do before committing ?
+------------------------------------
+
+PEP8-Compliancy
+---------------
+In order to maintain clear and user-friendly project, make sure that your
+changes respect PEP8 standards. PEP8 is a guide that provides Python coding
+conventions (naming, indentation,...).
+Official document : https://peps.python.org/pep-0008/
+
+To make sure your changes are PEP8 Compliant, different tools exist to help you
+here:
+    - linter (applicable on IDE) :
+        show some warning directly on IDE.
+    - pre-commit hook :
+        hook scripts that lint the added code using
+        flake8 and format it using black and isort.
+
+
+Typography
+----------
+Most of the comments made during PR-Reviewing are about typography/misspelling
+mistakes. An easy way to avoid these is by running
+`codespell <https://pypi.org/project/codespell/>`_ on your written code.
+
+
+Function type hinting
+---------------------
+In kiso-testing, every implemented function must have annotations for its
+parameters and return types (type hints). This results in increased readability and
+therefore in easier comprehension of the code for any reader.
+
+    .. code:: python
+
+        def some_fun(some_dict_param: dict, some_string_param: str) -> list:
+
+    .. note:: As not every types are available in the builtins, or as it is
+        important to precise inner type you might import some from collections
+        module or typing
+
+    .. code:: python
+
+        from typing import List
+        from collections import namedtuple
+
+        def some_fun(
+            some_int_list_param: List[int], some_imported_type_param: namedtuple
+        ) -> list:
+
+
+Unit Testing
+------------
+To ensure the correct behaviour of your code, add unit tests for every function
+you implemented.A convenient and pythonic way to do this is this is
+given by `pytest <https://docs.pytest.org/en/stable/>`_
+Code coverage is measured with `codecov <https://docs.codecov.com/docs>`_. It
+simply checks if the code coverage is not going lower than it was before changes.
+
+Examples Adaptation
+-------------------
+To ensure proper integration of your changes into the existing features,
+and demonstrate their usages, adapt the examples of modified module, and run
+it locally.
+
+Update Documentation
+--------------------
+Regarding documentation there are four main purposes that have to be fulfilled
+before committing :
+    - Documentation regarding the changes :
+        Make sure that the documentation allow easy understanding of the new
+        feature(s).This step mainly concern docstring (module, class, and function)
+        as shown below, but you could also have to change .rst documentation if
+        your changes concern general working principle of the ITF (e.g. cli)
+        To ensure proper formatting of the documentation, run ``invoke docs``
+        in the poetry environment.
+
+    .. code:: python
+
+        """
+        name_of_the_module
+        ******************
+
+        :module: name_of_the_module
+        :synopsis: short description of the module.
+
+        Extended description of the module's functionnality,
+        how it works, etc
+
+        .. currentmodule:: name_of_the_module
+        """
+
+    .. code:: python
+
+        class ClassName:
+        """Short description of class"""
+
+    .. code:: python
+
+        def fun(param1, param2):
+        """Short description of fun.
+
+        More extended description of the function
+        if needed.
+
+        :param param1: short description of param1
+        :param param2: short description of param2
+        :raise exception1: short description of raised exception
+
+        :return: short description of the return parameter
+        """
+
+    .. note:: Make also sure to do the type hinting for exceptions
+
+
+    - What's new section:
+        Add your changes into the what's new section, so user can stay updated of the
+        brand new features.
+
+    - Changelog:
+        Changelog is updated automatically with commit name. However commit names have
+        to respect specific norms. (Your changes concern a bug fix, commit name must be : "fix: commit name")
+        Further information on the naming can be found on: https://www.conventionalcommits.org/en/v1.0.0/)
+
+    - Documentation has to build properly.
+
 .. include:: getting_started_dev.rst