Open Stack

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150305/7fed0c9f/attachment.html>