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

docs: fix references to github repo #76

Merged
merged 2 commits into from
Jun 22, 2023

Conversation

marquiz
Copy link
Collaborator

@marquiz marquiz commented Jun 21, 2023

This relies on the myst parser's (new in v0.19) feature of customizing
external URL schemes with the "myst_url_schemes" configuration option.
We specify new URL schemes "blob" and "tree" which are supposed to be
used for references to blobs (files) and trees (directories) in the git
repo.

This also drops sphinx event hooks ("doctree-resolved" and
"missing-reference"), simplifying the conf.py considerably. They were
useless anyway as they were totally broken and didn't actually fix any
references to repo files.

The downside of this is that the affected references are not shown when
browsing .md files directly from github (as github dosn't handle our
custom 'tree:' and 'blob:' url schemes. However, it should be preferable
to have the cross-references working in the official documentation.

This PR also updates myst-parser to the latest version and pins the versions of
sphinx-rtd-theme and sphinx-markdown-tables for predictable results.

@marquiz marquiz force-pushed the devel/docs-update-deps branch 2 times, most recently from de12d4d to 4227e4d Compare June 21, 2023 14:28
@klihub
Copy link
Collaborator

klihub commented Jun 21, 2023

The downside of this is that the affected references are not shown when browsing .md files directly from github (as github dosn't handle our custom 'tree:' and 'blob:' url schemes. However, it should be preferable to have the cross-references working in the official documentation.

The best would be to get both working: keep the links working in the .md files and get them working in the generated documentation as well which I believe will require some python post-genertion fixup logic in the end. Why didn't the fixup in the event hooks work ?

Update myst-parser to the latest version. Also, pin the versions of
sphinx-rtd-theme and sphinx-markdown-tables for predictable results.

Signed-off-by: Markus Lehtonen <[email protected]>
This relies on the myst parser's (new in v0.19) feature of customizing
external URL schemes with the "myst_url_schemes" configuration option.
We specify new URL schemes "blob" and "tree" which are supposed to be
used for references to blobs (files) and trees (directories) in the git
repo.

This also drops sphinx event hooks ("doctree-resolved" and
"missing-reference"), simplifying the conf.py considerably. They were
useless anyway as they were totally broken and didn't actually fix any
references to repo files.

The downside of this is that the affected references are not shown when
browsing .md files directly from github (as github dosn't handle our
custom 'tree:' and 'blob:' url schemes. However, it should be preferable
to have the cross-references working in the official documentation.

Signed-off-by: Markus Lehtonen <[email protected]>
@klihub klihub merged commit b4308f1 into containers:main Jun 22, 2023
@marquiz marquiz deleted the devel/docs-update-deps branch June 22, 2023 10:20
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.

3 participants