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

Allow adding extra documentation in Markdown format #342

Open
ssbarnea opened this issue Sep 24, 2024 · 2 comments
Open

Allow adding extra documentation in Markdown format #342

ssbarnea opened this issue Sep 24, 2024 · 2 comments
Assignees
Labels
enhancement New feature or request

Comments

@ssbarnea
Copy link
Member

While Sphinx itself can use ME instead of RST via MyST sphinx plugin, anstibul-docs is unable to expose markdown files as links (even if sphinx does build the files correctly)

I am referring to https://ansible.readthedocs.io/projects/antsibull-docs/collection-docs/#adding-extra-documentation which documents on how to make extra documentation visible.

This problem is quite important because current collection packaging allows ONLY markdown documentation to be rendered in galaxy/hub, this being the only official way to ship documentation as part of the collection itself.

I suspect that this can easily be addressed by relaxing the check done by antsibull-docs.

@ssbarnea ssbarnea self-assigned this Sep 24, 2024
@ssbarnea ssbarnea added the bug Something isn't working label Sep 24, 2024
@felixfontein felixfontein added enhancement New feature or request and removed bug Something isn't working labels Sep 24, 2024
@felixfontein felixfontein changed the title Extra documentation cannot be added in markdown format Allow adding extra documentation in Markdown format Sep 24, 2024
@felixfontein
Copy link
Collaborator

Currently antsibull-docs only supports RST since we need to make sure that only labels that these documents insert into the global label namespace adhere to the requirements, namely that they are prefixed with ansible_collections.<namespace>.<name>.docsite..

So we need to find out a) what kind of labels MyST documents can insert in Sphinx, and b) how we can enumerate all these labels in antsibull-docs so we can only copy files which use correct labels.

@felixfontein
Copy link
Collaborator

https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html seems to describe references in MyST.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants