Doc8 rejecting a linenos attribute we need as a directive in openstackdoctools RST/Sphinx theme

[Anne Gentle]

We need to use a linenos directive built into Sphinx to get line number output for our HTML with the new openstackdocstheme.

https://wiki.openstack.org/wiki/Documentation/Migrate#Line_numbers_in_code_blocks

We've found that the doc8 does not recognize this flag on the highlight directive. http://sphinx-doc.org/markup/code.html

Excerpt from:
http://logs.openstack.org/83/158983/4/check/gate-openstack-manuals-tox-checkniceness/8ce681c/console.html

2015-02-26 00:35:42.145 | checkniceness runtests: commands[1] | doc8 doc
2015-02-26 00:35:42.148 | /home/jenkins/workspace/gate-openstack-manuals-tox-checkniceness$ /home/jenkins/workspace/gate-openstack-manuals-tox-checkniceness/.tox/checkniceness/bin/doc8 doc
2015-02-26 00:35:47.429 | Scanning...
2015-02-26 00:35:47.429 | Validating...
2015-02-26 00:35:47.429 | doc/networking-guide/scenario-l3ha-ovs.rst:223: D000 Error in "code-block" directive:
2015-02-26 00:35:47.429 | unknown option: "linenos".
2015-02-26 00:35:47.429 | doc/networking-guide/scenario-l3ha-ovs.rst:257: D000 Error in "code-block" directive:
2015-02-26 00:35:47.429 | unknown option: "linenos".
2015-02-26 00:35:47.429 | doc/networking-guide/scenario-l3ha-ovs.rst:305: D000 Error in "code-block" directive:
2015-02-26 00:35:47.429 | unknown option: "linenos".
2015-02-26 00:35:47.429 | doc/networking-guide/scenario-l3ha-ovs.rst:325: D000 Error in "code-block" directive:
2015-02-26 00:35:47.430 | unknown option: "linenos".
2015-02-26 00:35:47.430 | doc/networking-guide/scenario-l3ha-ovs.rst:378: D000 Error in "code-block" directive:
2015-02-26 00:35:47.430 | unknown option: "linenos".
2015-02-26 00:35:47.430 | doc/networking-guide/scenario-l3ha-ovs.rst:397: D000 Error in "code-block" directive:
2015-02-26 00:35:47.430 | unknown option: "linenos".
2015-02-26 00:35:47.430 | doc/networking-guide/scenario-l3ha-ovs.rst:411: D000 Error in "code-block" directive:
2015-02-26 00:35:47.430 | unknown option: "linenos".
2015-02-26 00:35:47.430 | doc/networking-guide/scenario-l3ha-ovs.rst:421: D000 Error in "code-block" directive:
2015-02-26 00:35:47.430 | unknown option: "linenos".
2015-02-26 00:35:47.430 | doc/networking-guide/scenario-l3ha-ovs.rst:457: D000 Error in "code-block" directive:
2015-02-26 00:35:47.430 | unknown option: "linenos".
2015-02-26 00:35:47.431 | doc/networking-guide/scenario-l3ha-ovs.rst:470: D000 Error in "code-block" directive:
2015-02-26 00:35:47.431 | unknown option: "linenos".
2015-02-26 00:35:47.431 | ========
2015-02-26 00:35:47.431 | Total files scanned = 53
2015-02-26 00:35:47.431 | Total files ignored = 0
2015-02-26 00:35:47.431 | Total accumulated errors = 10
2015-02-26 00:35:47.431 | Detailed error counts:
2015-02-26 00:35:47.431 | - doc8.checks.CheckCarriageReturn = 0
2015-02-26 00:35:47.431 | - doc8.checks.CheckIndentationNoTab = 0
2015-02-26 00:35:47.431 | - doc8.checks.CheckMaxLineLength = 0
2015-02-26 00:35:47.431 | - doc8.checks.CheckNewlineEndOfFile = 0
2015-02-26 00:35:47.432 | - doc8.checks.CheckTrailingWhitespace = 0
2015-02-26 00:35:47.432 | - doc8.checks.CheckValidity = 10
2015-02-26 00:35:47.454 | ERROR: InvocationError: '/home/jenkins/workspace/gate-openstack-manuals-tox-checkniceness/.tox/checkniceness/bin/doc8 doc'
2015-02-26 00:35:47.454 | checkniceness runtests: commands[2] | flake8
2015-02-26 00:35:47.457 | /home/jenkins/workspace/gate-openstack-manuals-tox-checkniceness$ /home/jenkins/workspace/gate-openstack-manuals-tox-checkniceness/.tox/checkniceness/bin/flake8
2015-02-26 00:35:47.963 | ___________________________________ summary ____________________________________
2015-02-26 00:35:47.963 | ERROR: checkniceness: commands failed

[Ian Cordasco (icordasc)]

So this appears to be a problem with restructuredtext-lint [1]. Since `:linenos:` is a sphinx-specific directive, we either need to update restructuredtext-lint to handle sphinx directives and options /or/ add a specific expression to ignore this particular warning in main (like the default excludes [2]).

[1]: https://github.com/twolfson/restructuredtext-lint

[2]: https://github.com/stackforge/doc8/blob/master/doc8/checks.py#L100..L105

[Anne Gentle (annegentle)]

Thanks Ian!

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/160053

[OpenStack Infra (hudson-openstack)]

Change abandoned by Anne Gentle (<email address hidden>) on branch: master
Review: https://review.openstack.org/160053
Reason: No need.

[Adam Spiers (adam.spiers)]

Years later, I'm still seeing this issue with I95a4b46fecaafafd1beb8314d1cf795b60fb17a8