Open Stack

On Fri, Mar 6, 2015 at 10:09 AM, Ian Cordasco <ian.cordasco at rackspace.com>
wrote:

> 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
>
>
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.


>     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.
>
>
Great tips, thanks! I've found this side-by-side editor very helpful:
http://rst.ninjs.org


> 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?
>
>
That invocation may be more helpful as we migrate and author, what do
others think?

Thanks,
Anne


> Cheers,
> Ian
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150307/7dd6785e/attachment.html>