<div dir="ltr">Hi all, <div><br></div><div>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. </div><div><br></div><div>Some examples:</div><div>- 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]<br>- 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.</div><div><div><br></div><div>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.</div><div><br></div><div><span style="color:rgb(0,0,0);font-family:sans-serif">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.</span><br></div><div><span style="color:rgb(0,0,0);font-family:sans-serif"><br></span></div><div><span style="color:rgb(0,0,0);font-family:sans-serif">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:</span></div><div><span style="color:rgb(0,0,0);font-family:sans-serif"><br></span></div><div>







<p class=""><span class=""><a href="https://review.openstack.org/161835">https://review.openstack.org/161835</a></span></p></div><div><span style="color:rgb(0,0,0);font-family:sans-serif"><br></span></div><div>Thanks,</div><div>Anne</div><div><span style="color:rgb(0,0,0);font-family:sans-serif"><br></span></div>-- <br><div class="gmail_signature">Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</div></div>