docs(readme): show only one level in table of contents

[noelmcloughlin]

This PR makes the table of contents less verbose (depth: 1).

Table of Contents

General notes
Contributing to this repo
Available states
Testing

The default depth (two) is too verbose for users.

The list of available states is not impacted by this update.

[noelmcloughlin]

OpenSuse Travis CI job failed. bundler: failed to load command: kitchen (/home/travis/build/saltstack-formulas/template-formula/vendor/bundle/ruby/2.4.0/bin/kitchen)

[myii]

@noelmcloughlin I can see advantages to both ways, so I'm not convinced on proceeding with the merge. The main reason being is that the current method has been in use for a long time (i.e. before all of these recent developments) so using this method would be inconsistent until it eventually propagated through all of the repos out there. The other thing is that we really should have the proper documentation solution in place before this propagation can complete, so that will introduce even more inconsistencies in the interim. Essentially, it may end up being a change for no real gain. However, I'm not going to get in the way if this is preferred by others as well.

[noelmcloughlin]

The repetition of "Available States" from usage of both "..contents:: table of contents" and "contents:: local" is unnecessary and removing the repetition feels more user friendly. An alternative option is to remove .. contents:: table of content from the README. However since documentation is WIP I can close this PR. wdyt

[myii]

@noelmcloughlin No need to close it, this is a valid idea. It's just horses for courses. Personally, I've got very used to seeing everything at the top, even since dealing with SaltStack Formulas. So I'd suppose that there are a few others like me, who wouldn't like to have to scroll down to "find" the states' list. Yes, there's some duplication but it doesn't cause any harm from an RST perspective. Still, some may suggest we should have one or the other, not both. And then there are some who prefer both...!

[noelmcloughlin]

It's hard to RTFM on some formula with many states. Lots of scrolling with mouse.

[baby-gnu]

I agree that we shouldn't have 2 listings. It should be either in TOC or locally under Available states.

I approve this PR since I find it more readable for new users:

1. Synopsis
2. Table of content to have a quick look and an easy jump
3. Explanation about the formula, mostly for new user I think ;-)

[myii]

@daks @n-rodriguez Can I pull you both in for this PR and number #169? You've both done a number of semantic-release conversions. Your opinions would be very useful, since this will lead to changing the structure across all of the formulas.

Personally, I'm OK either way. My only concern is consistency; whatever we agree on should be used across the org.

[n-rodriguez]

I approve this PR since I find it more readable for new users

#metoo

[myii]

While reviewing the lvm-formula PR, this requires adding the following under some/most of the main headings:

.. contents::
    :local:

So that will be needed here as well, when working in conjunction with #169.

[myii]

@noelmcloughlin Actual, since both ideas are getting approvals, why not fix #169 in this PR as well? That makes it easier to work out where the local contents are going to be needed.

[noelmcloughlin]

I'll handle #169 in another PR because this is now an "unknown branch". /shrug
Thanks, everyone for reviewing. Appreciated.

[saltstack-formulas-travis]

🎉 This PR is included in version 4.0.9 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀