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

Improve logical information for labels to Ansible objects #216

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

felixfontein
Copy link
Collaborator

@felixfontein felixfontein commented Sep 17, 2023

Fixes #203.

Current version (Zeal 'Sections' screenshot of HTML docsite converted with doc2dash):
image

The n-fold 'Requirements' section still shows up, but at least the references to all return values and options look much better! Also, there's now an index with all modules, plugins, and roles (if you tell Sphinx to generate it):

image

@felixfontein
Copy link
Collaborator Author

More Zeal screenshots:

The requirements references look better:
image

Return values for function-like plugins (lookups, filters, tests):
image

Nested return values for function-like plugins (lookups, filters, tests):
image

Building the official docsite with an appropriate theme and converting it with doc2dash should now produce a pretty neat docset.

@felixfontein
Copy link
Collaborator Author

One problem is that the current solution works well with HTML generation, but not at all with LaTeX. I tried to play around with that the last days, but didn't had much time, and the only way I got it to work with both HTML and LaTeX writers resulted in a large amount of WARNINGS and CRITICAL errors (which did not impact functionality, since the collisions they complained about were intentional).

I'll try to spend some more time figuring out how to do this properly...

@felixfontein
Copy link
Collaborator Author

I think a better way is to allow doc2dash to change/remove labels with a (say) JSON file, and then dump such a JSON file from antsibull-docs. That allows us to obtain all these extra details without doing dirty tricks to try to make Sphinx output the titles for references that we want in the Interspinx file.

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.

Improve logical information in Sphinx indexes
1 participant