Merge branch 'doc/cobertura-report-improvement' into 'master'

doc: cobertura report + commented code in template

See merge request to-be-continuous/python!47

README.md

@@ -84,42 +84,6 @@ The Python template features four alternative test jobs:
 * or `py-nosetest` that performs tests based on [nose](https://nose.readthedocs.io/en/latest/) Python lib,
 * or `py-compile` that performs byte code generation to check syntax if not tests are available.
 
-#### Activate code coverage report artifact
-
-Code coverage report artifact is disabled, due to a [deprecated syntax](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78132).
-
-To activate code coverage report artifact, you need to update python-test step depending on our gitlab version:
-* gitlab < 14.10 :
-```yaml
-artifacts:
-    name: "$CI_JOB_NAME artifacts from $CI_PROJECT_NAME on $CI_COMMIT_REF_SLUG"
-    expire_in: 1 day
-    when: always
-    reports:
-      junit:
-        - $PYTHON_PROJECT_DIR/reports/TEST-*.xml
-      cobertura: $PYTHON_PROJECT_DIR/reports/coverage.xml
-    paths:
-      - $PYTHON_PROJECT_DIR/reports/
-```
-
-* gitlab >= 14.10
-```yaml
-artifacts:
-    name: "$CI_JOB_NAME artifacts from $CI_PROJECT_NAME on $CI_COMMIT_REF_SLUG"
-    expire_in: 1 day
-    when: always
-    reports:
-      junit:
-        - $PYTHON_PROJECT_DIR/reports/TEST-*.xml
-    coverage_report:
-        ​coverage_format: cobertura
-        path: ​$PYTHON_PROJECT_DIR/reports/coverage.xml
-    paths:
-      - $PYTHON_PROJECT_DIR/reports/
-```
-
-
 #### `py-unittest` job
 
 This job is **disabled by default** and performs tests based on [unittest](https://docs.python.org/3/library/unittest.html) Python lib.
@@ -220,6 +184,31 @@ It is bound to the `build` stage, and uses the following variables:
 | --------------------- | ----------------------------------------------------------------------------- | ------------- |
 | `PYTHON_COMPILE_ARGS` | [`compileall` CLI options](https://docs.python.org/3/library/compileall.html) | `*`           |
 
+#### Activate code coverage report artifact
+
+Code coverage report artifact is disabled, due to a [deprecated syntax](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78132).
+
+In order to activate code coverage report artifact, you need to override your actual unit test job depending on our GitLab version.
+
+Here is an example with `py-pytest` job (change to `py-unittest` or `py-nosetests` depending on your unit tests library):
+
+* for GitLab < 14.10:
+```yaml
+py-pytest:
+  artifacts:
+    reports:
+      cobertura: $PYTHON_PROJECT_DIR/reports/coverage.xml
+```
+* for GitLab >= 14.10:
+```yaml
+py-pytest:
+  artifacts:
+    reports:
+      coverage_report:
+        ​coverage_format: cobertura
+        path: ​$PYTHON_PROJECT_DIR/reports/coverage.xml
+```
+
 ### SonarQube analysis
 
 If you're using the SonarQube template to analyse your Python code, here is a sample `sonar-project.properties` file:
@@ -343,8 +332,6 @@ You should disable the `semantic-release` job (as it's the `py-release` job that
 
 Finally, the semantic-release integration can be disabled with the `PYTHON_SEMREL_RELEASE_DISABLED` variable.
 
-####
-
 #### Git authentication
 
 A Python release involves some Git push operations.
@@ -360,7 +347,7 @@ The key should not have a passphrase (see [how to generate a new SSH key pair](h
 Specify :lock: `$GIT_PRIVATE_KEY` as secret project variable with the private part of the deploy key.
 
 ```PEM
------BEGIN OPENSSH PRIVATE KEY-----
+-----BEGIN 0PENSSH PRIVATE KEY-----
 blablabla
 -----END OPENSSH PRIVATE KEY-----
 ```

templates/gitlab-ci-python.yml

@@ -659,6 +659,13 @@ py-unittest:
     reports:
       junit:
         - $PYTHON_PROJECT_DIR/reports/TEST-*.xml
+      # declaring the Cobertura report depends on the GitLab version :(
+      # GitLab < 14.10
+      # cobertura: $PYTHON_PROJECT_DIR/reports/coverage.xml
+      # GitLab >= 14.10
+      # coverage_report:
+      #   ​coverage_format: cobertura
+      #   path: ​$PYTHON_PROJECT_DIR/reports/coverage.xml
     paths:
       - $PYTHON_PROJECT_DIR/reports/
   rules:
@@ -682,6 +689,13 @@ py-pytest:
     reports:
       junit:
         - $PYTHON_PROJECT_DIR/reports/TEST-*.xml
+      # declaring the Cobertura report depends on the GitLab version :(
+      # GitLab < 14.10
+      # cobertura: $PYTHON_PROJECT_DIR/reports/coverage.xml
+      # GitLab >= 14.10
+      # coverage_report:
+      #   ​coverage_format: cobertura
+      #   path: ​$PYTHON_PROJECT_DIR/reports/coverage.xml
     paths:
       - $PYTHON_PROJECT_DIR/reports/
   rules:
@@ -704,6 +718,13 @@ py-nosetests:
     reports:
       junit:
         - $PYTHON_PROJECT_DIR/reports/TEST-*.xml
+      # declaring the Cobertura report depends on the GitLab version :(
+      # GitLab < 14.10
+      # cobertura: $PYTHON_PROJECT_DIR/reports/coverage.xml
+      # GitLab >= 14.10
+      # coverage_report:
+      #   coverage_format: cobertura
+      #   path: ​$PYTHON_PROJECT_DIR/reports/coverage.xml
     paths:
       - $PYTHON_PROJECT_DIR/reports/
   rules: