Improve docs

[scottclowe]

I was trying and failing to get a regex;(regex-pattern) mapping key to work in my schema, so I had a look at the documentation and tried the regex;(regex-pattern) example on its own, and that didn't work either. So I decided to fix the documentation to have a working example here.

When doing this I got a little carried away and started making other improvements to the documentation, including some spelling and grammar corrections, and changes to the ordering of sections in the Validation Rules file.

Hope this is all okay!

[Grokzen]

LGTM :]

If you want before i merge this, you can add yourself to docs/Authors.md under the Documentation group (I think you have to make that group in that file). Also please add a line in ReleaseNotes.rst under a new section Next Release with short line describing the change. Something like improved documentation (scottclowe) Or something similar.

I will probably not make a new release right away after merging this and wait for some code change from elsewhere before doing it.

[scottclowe]

Okay, done.

I made a new Documentation group and put you and me in it. :)

[scottclowe]

Don't merge just yet.
I'm going to add a couple of examples to the matching-rule section, which doesn't have any yet.

[Grokzen]

@scottclowe Ok, i will wait some, just ping when you feel it is ready to merge

[scottclowe]

Sorry for the delay with the documentation. I did not have time to look at it for the last couple of weeks.

I am looking at it now and I was trying to understand what matching='*' was supposed to do, but I it doesn't seem to do what I expected. In fact, I think it is broken.

This succeeds:

# Data
- 55
# Schema
type: seq
matching: "*"
seq:
    - type: int
      range:
        min: 0
        max: 20

This breaks due to unspecified type in the subrule:

# Data
- 55
# Schema
type: seq
matching: "*"
seq:
    - range:
        min: 0
        max: 20

Can you explain what it is supposed to do?

[scottclowe]

Ping @Grokzen

[Grokzen]

@scottclowe What is the main reason to change from the markdown way of creating headings to use the rst way of creating headings? Also that you have mixed heading types inside the document, both md and rst O.o

I would prefer to stick with markdown as it works the best on github. Or do you have some other reason in mind?

[scottclowe]

The underline styles are all Markdown, not mixed.

They do not mention it in the GitHub Markdown Basics, but they do in the
official Markdown docs basics and detailed, and in this handy GitHub-centric cheat sheet.

You can see it renders correctly here.

If you prefer the atx-style headings with all #, I can swap them to that. The motivation was it made it a lot easier for me to tell the depth of the content when editing the unparsed .md file. I find the difference between ----------------- and ### is much more striking between ## and ###. But I am happy to change them back for internal consistency if you prefer that.

[Grokzen]

Good links there. I allways assumed that the atx-style was the only one that was valid in markdown and that the ------- layout was RST specific and that you had to choose either MD or RST here on github. Another thing i have allways gone with is that most other projects that have some kind of readme that i have seen is using the atx-style syntax for .md files.

I do would like to change back to atx-style because of a few reasons. I saw that it renders properly and that is not really the problem. The main thing i like is the consistency across all MD files in the docs to use the same syntax. If that syntax would be MD or RST is not a big issue as long as there is some chosen standard.

However, one thing worth mention is that i have had plans on moving all this docs to a proper readthedocs page and i do think that those pages is done with RST so the pages will be rewritten to RST in the future anyway :]

If you change the heading i will merge it after that as it LGTM :]

[scottclowe]

Fixed the headings so they are all # style now.

[Grokzen]

Many thanks for this great work @scottclowe :]