First of all, thank you for contributing to the documentation of Armarx!

To understand where content that was added to some documentation file will show up, it is beneficial to read the background section. Alternatively, you can directly follow links where to place specific documentation.

In all cases, the section how to actually write documentation files is helpful to understand which commands are best practise, and where typical problems might arise from.

To see a preview of your changes, refer to the section on generating the documentation. For in-depth information about all technical details, which are expected to be relevant only if you maintain the ArmarX documentation, refer to the last section.

Background

Work in progress, see the older Documentation page in the meanwhile.

Where to Place Documentation

Here are some locations to typically put documentation:

Writing your own package: Use a top-level README.md using the template, which is shown by Gitlab and (in the future) will be parsed to a Doxygen-based overview page
Writing a tutorial: Place it the tutorials folder of ArmarX Documentation, or of the respective package
Writing a HowTo: Place it in the HowTo folder of ArmarX Documentation, or of the respective package
Shortly explain a term: Add it to the Glossary in ArmarX Documentation
Explain a concept in depth: Create a stand-alone page, e.g., in the respective package, and link it in the concepts overview page of ArmarX Documentation
Document how to fix or investigate an error occuring at build time: Extend the respective overview in ArmarX Documentation, or extend the troubleshooting page of the respective package and link it in the overview
Document how to fix or investigate an error occuring at run time: Extend the respective overview in ArmarX Documentation, or extend the troubleshooting page of the respective package and link it in the overview
Just found a problem, and not being sure yet how to solve it: Open an issue, potentially add the documentation label, and create the (probably troubleshooting) entry as soon as you were told or found a solution

Writing Documentation Files

Work in progress, see the older Documentation page in the meanwhile.

Technical Details

Work in progress, see the older Documentation page in the meanwhile.