From 0e492f3fba585cc992adb905fc2abcb66b5e5859 Mon Sep 17 00:00:00 2001 From: Benoit Orihuela Date: Wed, 20 Nov 2024 17:01:13 +0100 Subject: [PATCH 1/2] doc: bootstrap a doc to help in troubleshooting documentation generation --- README.md | 7 +++++++ Troubleshoot_Documentation_Generation.md | 7 +++++++ 2 files changed, 14 insertions(+) create mode 100644 Troubleshoot_Documentation_Generation.md diff --git a/README.md b/README.md index 40b7def7..1352bf7b 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,14 @@ specification of the ETSI NGSI-LD API. - [Install the Test Suite](#install-the-test-suite) - [Configure the test suite](#configure-the-test-suite) - [Execute the NGSI-LD Test Suite](#execute-the-ngsi-ld-test-suite) +- [Use the Test Suite Management (tsm) tool](#test-suite-management-tsm) - [Contribute to the Test Suite](#contribute-to-the-test-suite) - [Install IDE (PyCharm)](#install-ide-pycharm) + - [Develop a new Test Case](#develop-a-new-test-case) - [Run configurations (PyCharm)](#run-configurations-pycharm) - [Pre commit](#pre-commit) - [Tooling](#tooling) +- [Coding style](#coding-style-of-test-suites) - [Frameworks and libraries used in the project](#frameworks-and-libraries-used-in-the-project) - [Useful links](#useful-links) - [LICENSE](#license) @@ -376,6 +379,10 @@ Finally, check that everything is OK by running the unit tests: python -m unittest discover -s ./doc/tests -t ./doc ``` +In order to help in investigating errors that can be encountered when generating the documentation, you can check in +the [Documentation generation troubleshoot document](Troubleshoot_Documentation_Generation.md) for further documentation +and tips. + ### Run configurations (PyCharm) Two sample configurations have been created: diff --git a/Troubleshoot_Documentation_Generation.md b/Troubleshoot_Documentation_Generation.md new file mode 100644 index 00000000..df10fb03 --- /dev/null +++ b/Troubleshoot_Documentation_Generation.md @@ -0,0 +1,7 @@ +# Troubleshoot the generation of the documentation + +## Permutations and setup keywords + +If a Test Case is built around permutations, you have to use the `Test Setup` (and `Test Teardown`) keywords in order +to properly generate the documentation. If you use `Suite Setup` (and `Suite Teardown`), the generated documentation +will not contain the full description of the setup step (it will not full but it will only contain the generic sentence). -- GitLab From ff986a8d08e9e1ed85b8beff7480cf6244f2e222 Mon Sep 17 00:00:00 2001 From: Benoit Orihuela Date: Wed, 20 Nov 2024 17:15:03 +0100 Subject: [PATCH 2/2] better describe the purpose of the troubleshoot entry --- Troubleshoot_Documentation_Generation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Troubleshoot_Documentation_Generation.md b/Troubleshoot_Documentation_Generation.md index df10fb03..508cb7aa 100644 --- a/Troubleshoot_Documentation_Generation.md +++ b/Troubleshoot_Documentation_Generation.md @@ -1,6 +1,6 @@ # Troubleshoot the generation of the documentation -## Permutations and setup keywords +## Missing setup step description If a Test Case is built around permutations, you have to use the `Test Setup` (and `Test Teardown`) keywords in order to properly generate the documentation. If you use `Suite Setup` (and `Suite Teardown`), the generated documentation -- GitLab