Open Stack

On 3/5/15, 12:56, "Anne Gentle" <annegentle at justwriteclick.com> wrote:

>Hi all, 
>
>
>You know me, I like gate tests on docs so that the robots can do what the
>humans shouldn't waste their time on. However I sense we're a bit too
>heavy-handed in the use of doc8 to where the value proposition in
>consistent markup doesn't meet our current
> needs. 
>
>
>Some examples:
>- Error in "code" directive: unknown option: "linenos". In fact we do
>want to enable linenos, but the linter in doc8 doesn't know about it. [1]
>- Anonymous hyperlink mismatch: 1 references but 0 targets. Here the
>author had a slightly different name for the hyperlink than what was in
>the text. [2] Seems this should be allowed if humans want it.
>
>
>Human eyes need to see if the output is what is wanted for both of these
>in order to know if the markup is correct.
>
>
>We have to be careful to make RST validation easier than docbook, since
>our move to RST is in order to enable more doc patches.
>
>
>
>So for now I'm posting a review to disable doc8 while we all get better
>at debugging source and output problems. Let me know your thoughts here:
>
>
>https://review.openstack.org/161835
>
>
>
>Thanks,
>Anne
>
>
>-- 
>Anne Gentle
>annegentle at justwriteclick.com

So the problem that a lot of people run into (and that used to be a
serious problem when trying to view reStructuredText on GitHub as a
rendered document) is that RST was designed specifically to be extensible
through roles and directives.

It looks as if the RST linter that doc8 leans on for most of its
validation is just doing standard RST linting and has no knowledge of the
directives and roles that Sphinx adds. Unfortunately it seems there isn’t
a linter built into it. It does, however, (when building) provide warning
and errors about problems with the document. Something like

    sphinx-build -q -E -b html doc/source doc/build

This will only output warnings and errors (likewise, if you only want
errors swap -q for -Q). It will also build from a fresh environment (to
ensure that any cached builds don’t lead to false positives) because it
uses -E.

Might help you catch errors in the meantime but it probably won’t provide
you with the same feedback as doc8.

Perhaps it makes sense to have doc8 as a non-voting job while the above
invocation runs as its own voting job?

Cheers,
Ian