RTK icon indicating copy to clipboard operation
RTK copied to clipboard

WIP: Setup Sphinx documetation for readthedocs

Open LucasGandel opened this issue 4 years ago • 2 comments

@SimonRit Here is a POC regarding automated online documentation.

This is far from being complete but it sets up the minimum infrastructure to automatically generate local and online documentation. We could keep pushing code to this PR until we have a complete documentation gathering all the resources already available online.

I tried to replicate the wiki applications pages into the examples directory. This cannot be built nor tested with CMake but it makes doc updates easier.

Support for existing markdown files has been added. An example is given by including GettingStarted.md in the main index.rst file.

Support for external images has been added. They can be added to any directory. The documentation/Sphinx/ExternalData folder is a good place to store images that should be included in the doc but that don't belong to any example.

An example of the resulting doc should be available here.

We can setup a call to review and discuss this PR together, just let me know.

LucasGandel avatar May 04 '20 15:05 LucasGandel

@SimonRit Images should now be fixed in the documentation. I could keep the original approach:

  • Images can be added using "content-files" referencing the sha512 from data.kitware. (see examples/FDK)
  • Images are automatically downloaded when building the doc.
  • Images must be referenced using relative path when included in .rst files (see here)

We can schedule a call to discuss this again.

LucasGandel avatar May 19 '20 11:05 LucasGandel

Thanks, it looks good. We now need to have an internal discussion to agree (or not) on this documentation format... and to write it.

SimonRit avatar May 19 '20 20:05 SimonRit