Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rework documentation #48

Closed
mwestphal opened this issue Nov 12, 2021 · 19 comments
Closed

Rework documentation #48

mwestphal opened this issue Nov 12, 2021 · 19 comments
Assignees
@mwestphal
Labels
type:documentation Improvements or additions to documentation
Milestone
2.0.0

Comments

@mwestphal
Copy link
Contributor

mwestphal commented Nov 12, 2021 •
edited
Loading

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 HTML doc on windows #47
    There is a few issues with this approach:
  1. Generic doc is duplicated two times
  2. Options/Hotkeys doc is duplicated three times
  3. main README.md is getting very long and hard to read

This should be improved, here is what we need to have:

  1. Complete user documentation should be available in a gitlab markdown format from the main README.md
  2. Complete user documentation should be available in the webdoc
  3. Limit duplication as much as possible

Here is a proposition to fix that:

  1. Put only the most esential and nice looking information in the main README.md
  2. Link from the main README.md to other logically organized .md files in a dedicated directory (see below for an example organization)
  3. Generate webdocumentation .md files during build thanks to cmake custom commands (see below for more info)
  4. If adressing HTML doc on windows #47, generate simple html doc during build OR generate actual web doc during build
  5. (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?)
  6. (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.
@mwestphal
Copy link
Contributor Author

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

@mwestphal mwestphal added the type:documentation Improvements or additions to documentation label Nov 23, 2021
@mwestphal mwestphal added this to the 1.3.0 milestone Dec 6, 2021
@mwestphal
Copy link
Contributor Author

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

@mwestphal mwestphal modified the milestones: 1.3.0, 2.0.0 Aug 14, 2022
@mwestphal
Copy link
Contributor Author

Doc should be added for the libf3d too.

@mwestphal mwestphal mentioned this issue Aug 24, 2022
Closed
32 tasks
@mwestphal
Copy link
Contributor Author

mwestphal commented Sep 3, 2022 •
edited
Loading

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 ?

@mwestphal
Copy link
Contributor Author

Please provide some feedback @Meakk

@mwestphal mwestphal self-assigned this Sep 25, 2022
@Meakk
Copy link
Member

Meakk commented Oct 3, 2022

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

@mwestphal
Copy link
Contributor Author 

- 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

@mwestphal
Copy link
Contributor Author

Trying github upload

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

@mwestphal
Copy link
Contributor Author

typical

@mwestphal mwestphal mentioned this issue Oct 9, 2022
Merged
3 tasks
@mwestphal
Copy link
Contributor Author

logo

@mwestphal
Copy link
Contributor Author

logo

@mwestphal
Copy link
Contributor Author

Uploading logo.png…

@mwestphal
Copy link
Contributor Author

logo

@mwestphal
Copy link
Contributor Author

Octicons-mark-github svg

@mwestphal
Copy link
Contributor Author

Octicons-mark-github svg

@mwestphal
Copy link
Contributor Author

logo32

@mwestphal
Copy link
Contributor Author

Fixed by #364

@mwestphal
Copy link
Contributor Author

a

@mwestphal
Copy link
Contributor Author

194735416-3f386437-456c-4145-9b5e-6bb6451d7e9a

@mwestphal mwestphal mentioned this issue Nov 11, 2022
Closed
7 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@mwestphal mwestphal

Labels
type:documentation Improvements or additions to documentation
Projects
None yet
Milestone
2.0.0
Development

No branches or pull requests
2 participants
@mwestphal @Meakk