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

Galaxy meta docs table #60171

Merged
merged 2 commits into from Aug 13, 2019

Conversation

@abadger
Copy link
Member

commented Aug 6, 2019

SUMMARY

Update the generated collections meta doc with an rst table

ISSUE TYPE
  • Docs Pull Request
COMPONENT NAME
ADDITIONAL INFORMATION

This is built on top of #60148 and that should be merged first and this second.

@abadger abadger force-pushed the abadger:galaxy-meta-docs-table branch from a4872f4 to 5cdcd33 Aug 6, 2019

- This can be a company/brand/organization or product namespace under which all content lives.
- May only contain alphanumeric characters and underscores. Additionally namespaces cannot start with underscores or
numbers and cannot contain consecutive underscores.
description: |

This comment has been minimized.

Copy link
@jborean93

jborean93 Aug 6, 2019

Contributor

Why this change, it seems to move away from how we handle entries in module docs where a new list entry in a newline and now we can't wrap the text at 120 characters without it being a literal newline in the description.

This comment has been minimized.

Copy link
@abadger

abadger Aug 6, 2019

Author Member

Also change the structure of one description to test that both ways of
formatting the description work

I was debating whether to change this back after testing it.... On the one hand, changing it back will make everything match. On the other hand, there would be nothing testing that both ways work so it will be very easy for this formatting to break.

Perhaps it would be better if we remove the code supporting the second form of formatting instead?

(Also note, it's quite possible that module docs work with both syntaxes as well but we just don't have docs which are using that either...)

This comment has been minimized.

Copy link
@abadger

abadger Aug 7, 2019

Author Member

I just tested what module docs do. The module description actually renders a list as a list. It tries to render double-newline spaced paragraphs but is buggy (It renders paragraphs but starts with an initial bullet so that there is an error in the output)

The parameter descriptions must be a list. Newlines are swallowed rather than rendering new paragraphs.

This comment has been minimized.

Copy link
@abadger

abadger Aug 7, 2019

Author Member

After jborean prompted me to look at this further, the code in the template isn't there for the reason that I thought. The API between reading the source material and passing to the template could be changed to make it clearer what's happening. I'll fix that up both here and in the plugin_docs.

This comment has been minimized.

Copy link
@abadger

abadger Aug 7, 2019

Author Member

Fixed now.

plugin_docs actually already normalized options['description'] (but not the main module description) in the plugin portion. The template just needed to have the logic stripped out of it. (I updated the module description to match).

collection_meta now does the same thing: normalizes the data in the plugin and then the template can do its work without two code paths.

@abadger abadger force-pushed the abadger:galaxy-meta-docs-table branch from 5cdcd33 to 756aedd Aug 6, 2019

@ansibot

This comment has been minimized.

Copy link
Contributor

commented Aug 6, 2019

@ansibot

This comment has been minimized.

Copy link
Contributor

commented Aug 6, 2019

@abadger abadger force-pushed the abadger:galaxy-meta-docs-table branch 3 times, most recently from a3a034d to 491c5f8 Aug 7, 2019

@abadger

This comment has been minimized.

Copy link
Member Author

commented Aug 7, 2019

Here's a screenshot of the new table:

https://toshio.fedorapeople.org/ansible/new-collection-meta.png

It's pretty close to the present table so I think it's good to go.

@abadger abadger referenced this pull request Aug 7, 2019

abadger added some commits Jul 19, 2019

Use an rst table instead of a raw html table
* Rst is easier to read so we want to use it wherever possible
* Fix the jinja2 filters which create links so that they do not include
  extraneous whitespace in the URL

@abadger abadger force-pushed the abadger:galaxy-meta-docs-table branch from 491c5f8 to 2ed856f Aug 8, 2019

@acozine acozine referenced this pull request Aug 13, 2019
@acozine

This comment has been minimized.

Copy link
Contributor

commented Aug 13, 2019

Thanks @abadger and @jborean93.

@acozine acozine merged commit d9b3af5 into ansible:devel Aug 13, 2019

1 check passed

Shippable Run 136342 status is SUCCESS.
Details

@abadger abadger deleted the abadger:galaxy-meta-docs-table branch Aug 13, 2019

nkatarmal-crest added a commit to ciscoecosystem/ansible that referenced this pull request Aug 22, 2019

Galaxy meta docs table (ansible#60171)
* Use an rst table instead of a raw html table

* Rst is easier to read so we want to use it wherever possible
* Fix the jinja2 filters which create links so that they do not include
  extraneous whitespace in the URL

* Normalize description data before sending them to the templates
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.