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

doc: improve generated scion and scion-pki documentation #4331

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

oncilla
Copy link
Contributor

@oncilla oncilla commented Mar 14, 2023

Unify the documentation generation command for scion and scion-pki. Instead of rst, produce markdown which is easier to process.

Properly handled references between the individual commands. This way, we even get proper indexing in the toc tree on the side.
image


This change is Reviewable

Unify the documentation generation command for scion and scion-pki.
Instead of rst, produce markdown which is easier to process.

Properly handled references between the individual commands. This way,
we even get proper indexing in the toc tree on the side.
@oncilla oncilla requested a review from matzf March 14, 2023 19:24
@matzf
Copy link
Contributor

matzf commented Mar 14, 2023

Can we defer this until #4325?
If we add a customized gendoc tool, I'd prefer it to spit out something similar to manually written RST using all the nice sphinx features for layout and cross-referencing of command line options (e.g. .. option::).

@matzf
Copy link
Contributor

matzf commented Apr 3, 2023

I just came across sphinx-contrib/datatemplates. This allows to write a template .rst file and render it using data from yaml/json files.
Perhaps this could be a way to allow generating the content of commandline docs as we currently do, but allow keeping the markup styling as part of the documentation tree.

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