f3d Rework documentation

trafficstars

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

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, 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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&|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.

Nov 12 '21 22:11 mwestphal

https://gitlab.kitware.com/f3d/f3d/-/issues/236

Nov 12 '21 22:11 mwestphal

@Meakk : for the time being, lets keep update the ReadME.md, but lets not touch the old doc for the website.

Dec 17 '21 21:12 mwestphal

Doc should be added for the libf3d too.

Aug 24 '22 09:08 mwestphal

Here is a an updated plan for the new doc:

- README.md: contains generic presentation, link to release, quick how to use and acknoledgements
- GALLERY.md: same content as https://f3d-app.github.io/f3d/gallery/
- doc
-- OPTIONS.md: contains # Options
-- HOTKEYS.md: contains # Interaction and # Cycling coloring
-- INSTALATION.md: contains # Instalation
-- USAGE.md: contains # File Formats, # Scene construction, # rendering precedence, and anything else 
-- CONFIGURATION_FILE.md:  contains # Configuration File
-- DESKTOP_INTEGRATION.md: contains # Desktop Integration
-- LIMITATIONS.md: contains # Limitations
-- TROUBLESHOOTING.md: contains # Troubleshooting
-- dev
--- BUILD.md: contains # Build
--- GENERATE_COVERAGE.md: info about generating coverage
--- GENERATE_MAN.md: info about generating man
--- DEVELOP.md: info about our process of developement and how to contribute to f3d
-- libf3d
--- OVERVIEW.md: generic information about the libf3d, partially contains README_libf3d.md
--- EXAMPLES.md: expanded set of examples usage of the libf3d, insipired by README_libf3d.md
--- doxygen: not sure of the feasiability of this, but doxygen should be used to generate actual ref for libf3d

wdyt @Meakk @Audrey_il_te_faut_un_compte_github ?

Sep 03 '22 05:09 mwestphal

Please provide some feedback @Meakk

Sep 25 '22 07:09 mwestphal

We need a section for python/java bindings, otherwise looks good to me.

Oct 03 '22 14:10 Meakk

- README.md: contains generic presentation, link to release, quick how to use and acknoledgements
- GALLERY.md: same content as https://f3d-app.github.io/f3d/gallery/
- doc
-- OPTIONS.md: contains # Options
-- HOTKEYS.md: contains # Interaction and # Cycling coloring
-- INSTALATION.md: contains # Instalation
-- USAGE.md: contains # File Formats, # Scene construction, # rendering precedence, and anything else 
-- CONFIGURATION_FILE.md:  contains # Configuration File
-- DESKTOP_INTEGRATION.md: contains # Desktop Integration
-- LIMITATIONS.md: contains # Limitations
-- TROUBLESHOOTING.md: contains # Troubleshooting
-- dev
--- BUILD.md: contains # Build
--- GENERATE_COVERAGE.md: info about generating coverage
--- GENERATE_MAN.md: info about generating man
--- DEVELOP.md: info about our process of developement and how to contribute to f3d
-- libf3d
--- OVERVIEW.md: generic information about the libf3d, partially contains README_libf3d.md
--- EXAMPLES.md: expanded set of examples usage of the libf3d, insipired by README_libf3d.md
--- BINDINGS.md
--- doxygen: not sure of the feasiability of this, but doxygen should be used to generate actual ref for libf3d

Oct 08 '22 01:10 mwestphal

Trying github upload

dota can.webm dota.webm directScalars gearbox.webm pointCloud volumeMedical cfd realisticMask fbx step realisticHelmet volume cad