<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Mar 6, 2015 at 10:09 AM, Ian Cordasco <span dir="ltr"><<a href="mailto:ian.cordasco@rackspace.com" target="_blank">ian.cordasco@rackspace.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class=""><div class="h5">On 3/5/15, 12:56, "Anne Gentle" <<a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a>> wrote:<br>
<br>
>Hi all,<br>
><br>
><br>
>You know me, I like gate tests on docs so that the robots can do what the<br>
>humans shouldn't waste their time on. However I sense we're a bit too<br>
>heavy-handed in the use of doc8 to where the value proposition in<br>
>consistent markup doesn't meet our current<br>
> needs.<br>
><br>
><br>
>Some examples:<br>
>- Error in "code" directive: unknown option: "linenos". In fact we do<br>
>want to enable linenos, but the linter in doc8 doesn't know about it. [1]<br>
>- Anonymous hyperlink mismatch: 1 references but 0 targets. Here the<br>
>author had a slightly different name for the hyperlink than what was in<br>
>the text. [2] Seems this should be allowed if humans want it.<br>
><br>
><br>
>Human eyes need to see if the output is what is wanted for both of these<br>
>in order to know if the markup is correct.<br>
><br>
><br>
>We have to be careful to make RST validation easier than docbook, since<br>
>our move to RST is in order to enable more doc patches.<br>
><br>
><br>
><br>
>So for now I'm posting a review to disable doc8 while we all get better<br>
>at debugging source and output problems. Let me know your thoughts here:<br>
><br>
><br>
><a href="https://review.openstack.org/161835" target="_blank">https://review.openstack.org/161835</a><br>
><br>
><br>
><br>
>Thanks,<br>
>Anne<br>
><br>
><br>
>--<br>
>Anne Gentle<br>
><a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a><br>
<br>
</div></div>So the problem that a lot of people run into (and that used to be a<br>
serious problem when trying to view reStructuredText on GitHub as a<br>
rendered document) is that RST was designed specifically to be extensible<br>
through roles and directives.<br>
<br>
It looks as if the RST linter that doc8 leans on for most of its<br>
validation is just doing standard RST linting and has no knowledge of the<br>
directives and roles that Sphinx adds. Unfortunately it seems there isn’t<br>
a linter built into it. It does, however, (when building) provide warning<br>
and errors about problems with the document. Something like<br>
<br></blockquote><div><br></div><div>Yes, it's the linter that I specifically want to be more robust, and I don't want us to be stalled in our migration while bugs get fixed in it. I will say I appreciate the responsiveness there.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
    sphinx-build -q -E -b html doc/source doc/build<br>
<br>
This will only output warnings and errors (likewise, if you only want<br>
errors swap -q for -Q). It will also build from a fresh environment (to<br>
ensure that any cached builds don’t lead to false positives) because it<br>
uses -E.<br>
<br></blockquote><div><br></div><div>Great tips, thanks! I've found this side-by-side editor very helpful: <a href="http://rst.ninjs.org">http://rst.ninjs.org</a></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Might help you catch errors in the meantime but it probably won’t provide<br>
you with the same feedback as doc8.<br>
<br>
Perhaps it makes sense to have doc8 as a non-voting job while the above<br>
invocation runs as its own voting job?<br>
<br></blockquote><div><br></div><div>That invocation may be more helpful as we migrate and author, what do others think?</div><div><br></div><div>Thanks,</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Cheers,<br>
Ian<br>
<br>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature">Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</div></div>