Discuss: Multiple example configurations

[wizonesolutions]

What do you think of keeping example.settings.yml as-is but also having an example-full.settings.yml? Sort of like how MySQL comes with examples for different installation sizes.

This would contain all variables (most commented out like before). When I'm configuring Vlad, it'd be easier for me to open up such a file in my IDE then to leave my IDE, go to my browser, and look up the thing I need. Especially for variables I consider fairly common like...um...what was it called.../checks docs/...oh yeah, db_import_up!

Anyway, I totally understand wanting to keep the example file that most people will look at and copy first simple, since it shows the bare minimum needed to get Vlad going. Just thought I'd raise this and get your thoughts.

[philipnorton42]

Yeah, we did originally have a large example settings file but we removed it as 1) it was scary for new users and 2) it was a pain to maintain.

That's the only issue with a large and utterly complete settings file, we would need to keep on top of updating it. It's also worth having it within the codebase as well so they can be quickly referenced. In fact, all of the settings are in the code base, they all have default values in /defaults in each role so we might be able to create a large settings file that in an automated manner...

Maybe we could have a number of setups in a examples/ directory? That would allow a user wanting to use a Varnish setup a setting file they can use almost straight away. That would also make testing slightly easier as we wouldn't need to plug in and out settings in a single file.

[wizonesolutions]

Yeah, my suggestion is to have a secondary example settings file, and maybe tag it with something new users can ignore like example detailed.settings.yml.

But an /examples directory or automated documentation of /defaults sounds even better. Probably the former is most practical to start with. Honestly, I don't care about all settings, but there are a few common settings that I have to go out to the docs to find now, and heck, even a note in the existing settings about where I can find the default values for everything (are those annotated?) would be useful. Something I can copy paste without leaving my IDE :)

Or: Get your documentation into Dash somehow.

[dixhuit]

I'd love to make the docs compatible with Dash. I use Dash loads already and love it. I've already checked out the feasibility but there's still no easy route for us that doesn't involve boat loads of extra work. This is about as close as it gets for now: https://github.com/rtfd/readthedocs.org/issues/662

automated documentation of /defaults

I prefer this over maintaining any additional docs within Vlad itself. There's plenty to maintain already, we need less, not more. And this is an automation project, no? Let's automate stuff :)

This approach may not be that straight forward if the galaxy branch ever sees the light of day and scales to the level that I'm thinking. IMHO I think we should park issues like this until we get our ducks in a row regarding galaxy otherwise we'll be in danger of doing things twice or doing things and then binning them. @wizonesolutions if you want to help in that department, then please feel free to checkout galaxy, get testing and add your voice to #262.

[wizonesolutions]

Understandable. I might have to check out the galaxy branch...what's it about?

On Thu, Aug 13, 2015 at 11:12 AM, Dan Bohea notifications@github.com wrote:

I'd love to make the docs compatible with Dash. I use Dash loads already and love it. I've already checked out the feasibility but there's still no easy route for us that doesn't involve boat loads of extra work. This is about as close as it gets for now: rtfd/readthedocs.org#662 https://github.com/rtfd/readthedocs.org/issues/662

automated documentation of /defaults

I prefer this over maintaining any additional docs within Vlad itself. There's plenty to maintain already, we need less, not more. And this is an automation project, no? Let's automate stuff :)

This approach may not be that straight forward if the galaxy branch ever sees the light of day and scales to the level that I'm thinking. IMHO I think we should park issues like this until we get our ducks in a row regarding galaxy otherwise we'll be in danger of doing things twice or doing things and then binning them. @wizonesolutions https://github.com/wizonesolutions if you want help in that department, then please feel free to checkout galaxy, get testing and add your voice to #262 https://github.com/hashbangcode/vlad/issues/262.

— Reply to this email directly or view it on GitHub https://github.com/hashbangcode/vlad/issues/267#issuecomment-130587154.

[dixhuit]

Understandable. I might have to check out the galaxy branch...what's it about?

Struggling to correctly detect sarcasm here :) Really? What's the GALAXY branch about?

Start by catching up on #262. Post questions there if you need more clarity.

[wizonesolutions]

No, I haven't looked at it before. It's obviously related to Ansible Galaxy, and if that's the only change, then I understand why it sounded sarcastic :)

OK, thanks.

On Thu, Aug 13, 2015 at 1:17 PM, Dan Bohea notifications@github.com wrote:

Understandable. I might have to check out the galaxy branch...what's it about?

Struggling to correctly detect sarcasm here :) Really? What's the GALAXY https://galaxy.ansible.com/ branch about?

Start by catching up on #262 https://github.com/hashbangcode/vlad/issues/262. Post questions there if you need more clarity.

— Reply to this email directly or view it on GitHub https://github.com/hashbangcode/vlad/issues/267#issuecomment-130624923.

[dixhuit]

LOL. OK, cool :)

[zxaos]

@danbohea That doc issue re: readthedocs/dash is not likely to get traction IMO. A workaround might be since the documentation is already in markdown, to do something like write a build process that converts it to HTML (say with pandoc, markdown-js, etc) and then use Dashing to turn the HTML into a dash docset. Seems to be the closes to an official way of doing it - see https://kapeli.com/docsets#dashDocset

[philipnorton42]

This is sort of morphing into a discussion about how to convert the codebase into documentation automatically. Whilst I think that approach is definitely something to consider I think we should move that over to the docs repo. However, the idea behind this issue (creating sample configs) is still something we should do. Even if it just going into the documentation.