I’m starting to write a more extended documentation for those OTB applications that I use. I’d like to do it in such a way that others could benefit from it and, eventually, suggest corrections.
Which would be the best tool for doing it? It has to be something easy that I could write in i.e. markdown and put up to a github or alike. Somehow cloning selected current help pages might be a good alternative, but do not know how to do it.
Agus
Hi,
Probably the best would be to fit that in the existing documentation ( https://www.orfeo-toolbox.org/CookBook/ ). It is in RST, so easy to write, and sources are located inside OTB, so it is already managed by gitlab, including continuous integration that builds the doc ( https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/-/tree/develop/Documentation/Cookbook ). Would it fit in the recipes section ? You can also create a section of your own. Contribution would go through the classical merge request process.
1 Like
where in gitlab would I find the rst of https://www.orfeo-toolbox.org/CookBook/Applications/app_DimensionalityReduction.html ?
Hello,
The documentation of applications is in the sources, for example for dimensionality reduction it is in this file. The different sections of the documentation is set by the SetName, SetDescription, SetDocLongDescription, SetDocLimitations, SetDocAuthors , SetDocSeeAlso, AddDocTag and SetParameterDescription methods.
This script then generate the rst from the application.
Cédric
This script then generate the rst from the application.
where is the rst file saved to? I just find the html (as in the aforementioned example).
What the external contributors could do is to edit the rst files. No way we can go to the *.cxx file and modify there: it would be inconvenient for the contributor and dangerous for the development. The idea is that contributors would make an extended documentation for selected applications and parts of this documentation could eventually make it to the “normal” documentation if the developper considers it is worthwhile.
These rst files are generating when building the documentation, but they are not exported on the website (onl the html output is exported). A tar with the rst output could be provided, but is it the best way to handle external contribution to documentation ? In my opinion having to find the corresponding rst, edit it and provide it does not make it easier, neither for the contributor, nor for the develop who have to extract the info from the rst and copy it to the .cxx.
I think the easiest way is to open an issue on the gitlab, with the proposed modifications (without worrying about the layout) and let the developers integrate the changes in the source code.
Note : this is the rst file for DimensionalityReduction, from a local build.
app_DimensionalityReduction.rst (4.9 KB)
Cédric
That would work for minor modifications only. I’m thinking on an extended documentation made by users for users. The rst would be a lot better, I can convert to markdown and edit with Typora in WYSIWYG:
Then upload to github or alike.
But I understand generating all rst files is work. I’ll see if I can manage to generate those I need myself.