Rework documentation
Documentation is hard to maintain, here is the current state:
- README.md contains the whole user documentation
- GENERATE.md contains some developper oriented documentation
- documentation/* contains a duplicate, segmented and slightly modified version of the README.md
- src/F3DOptions code contains options, hotkeys and examples documentations to be delivered with --help
- man contains documentations generated from --help and --version
- We potentially will have one more version of the doc thanks to #235 (closed)
There is a few issues with this approach:
- Generic doc is duplicated two times
- Options/Hotkeys doc is duplicated three times
- main README.md is getting very long and hard to read
This should be improved, here is what we need to have:
- Complete user documentation should be available in a gitlab markdown format from the main README.md
- Complete user documentation should be available in the webdoc
- Limit duplication as much as possible
Here is a proposition to fix that:
- Put only the most esential and nice looking information in the main README.md
- Link from the main README.md to other logically organized .md files in a dedicated directory (see below for an example organization)
- Generate webdocumentation .md files during build thanks to cmake custom commands (see below for more info)
- If adressing #235 (closed), generate simple html doc during build OR generate actual web doc during build
- (Optional) Find a way to generate a .h from the options/hotkeys .md file during build so that it can be used in the --help output (and other usages?)
- (Optional) Use Pandoc instead of help2man to generate man, relying on generated .md file during build (see expected format here: https://www.pragmaticlinux.com/2021/01/create-a-man-page-for-your-own-program-or-script-with-pandoc/)
Example .md file organization, that could also be used as a webdoc organisation:
- README.md
- doc
-- OPTIONS.md
-- HOTKEYS.md
-- INSTALATION.md
-- USAGE.md
-- BUILD.md (should this go into dev?)
-- CONFIGURATION_FILE.md
-- LIMITATIONS.md
-- TROUBLESHOOTING.md
-- dev
--- GENERATE_WEBDOC.md
--- GENERATE_COVERAGE.md
--- GENERATE_MAN.md
--- DEVELOP.md
- webdoc
...
Differences between README.md and webdoc md files:
- Image paths are differents (could be fixable):
+ ![F3D Logo](./resources/logo.svg)
- ![F3D Logo](logo.png)
+ <img src="https://kitware.github.io/F3D/gallery/04-f3d.png" width="640">
- ![F3D Demo](../gallery/04-f3d.png)
- many nbsp in the webdoc (could be fixable?)
+ Options &|Description
- Options|Description
- Internals links are removed (should be fixable)
+ See the coloring cycle section for more info.
- See the [coloring cycle](#Cycling Coloring) section for more info.
If all slight change are removed, simply symlinking from the webdoc to the doc.md could be a very easy solution to put into place.
Edited by Mathieu Westphal (Kitware)