Documentation

Summary

Minimal documentation is written now and shows up on docs.indiscale.com.

Focus

• Is the documentation correct and complete?
• Is the minimal example enough for users to get started?
• Is it acceptable that the API documentation is outside sphinx?

Test Environment

• Build: make doc_clean; make doc
• Open the html: xdg-open build/doc/html/index.html
• To test the pages build: download the artifact directory from the pipeline, extract it and inspect the index.html inside.

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass -> integration test is allowed to fail since no corresponding repo exists there.
• Reference related Issues: for caosdb/customers/lfpb/management#417
• Up-to-date CHANGELOG.md
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there spezifications? Are they satisfied?

For further good practices have a look at our review guidelines.

TODO

• Add description to README_SETUP.md: how to run unit tests locally

README_SETUP.md

@@ -10,6 +10,7 @@ This package requires the following software:
 - For running this library, a valid libcaosdb configuration is needed, for example a
   `.caosdb_client.json` file in your home directory or current working directory.  Please look at
   [`README_SETUP.md` in caosdb-cpplib](https://gitlab.indiscale.com/caosdb/src/caosdb-cpplib/-/blob/main/README_SETUP.md) for more information.
+* MOxUnit for unit tests, see below.
 
 ## Install and Load
 
@@ -22,6 +23,10 @@ This package requires the following software:
 
 ## Run Unit Tests
 
+* run `make test`
+
+### Requirements
+
 We use the standard test framework of Octave.
 
 See [this article](https://wiki.octave.org/Tests) for a primer and use
@@ -59,3 +64,7 @@ static website. If you rather would like to use the native,
 - `sphinx`
 - `sphinx-autoapi`
 - `recommonmark`
+- The Octave package `generate-html`, install it with
+  ```sh
+octave --eval "pkg install 'https://downloads.sourceforge.net/project/octave/Octave%20Forge%20Packages/Individual%20Package%20Releases/generate_html-0.3.2.tar.gz'"
+  ```