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.

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

Setup Sphinx documentation #346

Merged
merged 1 commit into from
Jul 25, 2024
Merged

Conversation

LucasGandel
Copy link
Collaborator

@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
Copy link
Collaborator Author

@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.

@SimonRit
Copy link
Collaborator

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

@LucasGandel LucasGandel force-pushed the sphinx-doc branch 4 times, most recently from 3ed1b9a to da81f4f Compare July 19, 2024 12:23
@LucasGandel LucasGandel changed the title WIP: Setup Sphinx documetation for readthedocs Setup Sphinx documentation Jul 19, 2024
@LucasGandel
Copy link
Collaborator Author

PR updated, a preview of the generated doc is available here: https://lucasgandelrtk.readthedocs.io/en/latest/

A README file has been added to share instructions on how to extend the doc.

Note that the top level index.md file must be placed next to the conf.py file. Because we want the documentation files to be spread across the sources, both index.md and conf.py must be at the root of the RTK source tree.

Copy link
Collaborator

@SimonRit SimonRit left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great, I only have minor suggestions. I will split examples into "Code examples" and "Applications examples" with a top page explaining the difference but that's up to me to do it. Thanks @LucasGandel!
Any preference between merging as is or taking over the PR to add more content?

GettingStarted.md Outdated Show resolved Hide resolved
conf.py Show resolved Hide resolved
documentation/docs/README.md Outdated Show resolved Hide resolved
@LucasGandel
Copy link
Collaborator Author

This is great, I only have minor suggestions. I will split examples into "Code examples" and "Applications examples" with a top page explaining the difference but that's up to me to do it. Thanks @LucasGandel! Any preference between merging as is or taking over the PR to add more content?

Suggestions have been addressed. I think it is better to merge this now and setup the readthedocs build with your account. Once it is up and running, we can make changes to the doc in new MRs

@SimonRit SimonRit merged commit 6f02ccb into RTKConsortium:master Jul 25, 2024
37 of 55 checks passed
@LucasGandel LucasGandel deleted the sphinx-doc branch July 25, 2024 13:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants