Docs for Galaxy roles

[dixhuit]

We need to consider how best to connect documentation in Galaxy roles to Vlad's main docs. Initially I'm just thinking about providing a clear list of links - anything more at this stage would be jumping the gun possibly.

The suggestion of adding a new section entitled "Roles" or "Extensions" appeals but I'm unsure about how best to word things:

• "Roles" possibly assumes too much Ansible familiarity (counter arg: tough, it's relevant, keep up, it's only one new word to learn)
• "Extensions" may be too much of an abstraction, especially given that there's already a word for these things ("roles").

I'll go right ahead and add the content to the dev branch of the docs but I'd like this to be briefly considered at least before another release is tagged.

[philipnorton42]

I was thinking about this last night, but it was more a case of just tying everything together. As they are in different repos it would make the "automated documentation" slightly more tricky, but not impossible.

I think that even though they are galaxy roles they should still be part of the main documentation (and indeed the main project) as they can be turned on or off via a single variable change.

Unless we want to go down the route of completely removing them from Vlad and allow their inclusion via some extra configs? I don't think doing that is the best plan though.

[dixhuit]

As they are in different repos it would make the "automated documentation" slightly more tricky, but not impossible.

Agreed, hence why I think that just linking them up for now is a nice easy first step.

I think that even though they are galaxy roles they should still be part of the main documentation (and indeed the main project)...

My main concern with this is that changes to a role's docs would require a change in 2 places (the role repo and Vlad's own docs). Linked docs, while a bit too minimal, do solve this. Automated docs (including partially scraped README files?) could be the best of both worlds. (but as you say, slightly more tricky). The solution to this though is perhaps another open source project in itself - Vlad can't be the only Ansible based project that faces this complication.

...as they can be turned on or off via a single variable change.

Indeed they could, but that var that handles that is still in Vlad itself and therefore the documentation of that var would be in Vlad's own docs (at least that's how I see it, that's also how it currently is for the few Galaxy roles that we currently include).

Unless we want to go down the route of completely removing them from Vlad and allow their inclusion via some extra configs? I don't think doing that is the best plan though.

Not sure I follow you 100% here. Are you referring to current "internal" Vlad roles that have yet to be abstracted out to Galaxy?

[dixhuit]

Initial docs page now live to at least cover us for now.

http://vlad-docs.readthedocs.org/en/latest/usage/galaxy_roles