Adding a unit test to verify the use of the `linenothreshold` option
provided by the `highlight` directive [1]. The included document to test
will introduce two sets of `code-block` and `literalinclude` directives
where the first entry generates contents using line numbers and the
second entry generates contents not using line numbers, respectfully.
[1]: https://github.com/sphinx-doc/sphinx/blob/v1.8.4/sphinx/transforms/post_transforms/code.py#L85
Signed-off-by: James Knight <james.d.knight@live.com>
Now that `highlightlang` directive is deprecated [1], the
`linenothreshold` option is to be used via the `highlight` directive.
The `highlight` directive will walk-through literal blocks to apply a
`linenos` value if:
1) The literal block has not been explicitly configured with the
`linenos` option.
2) If there is enough content (when comparing literal block's line
count to `linenothreshold`) that `linenos` should be explicitly
enabled or disabled [2].
While the `hightlight` directive should be able to explicitly define if
a literal block needs to enable line numbers, the logic is always
ignored since the code block and literal include directives already
configures `linenos` when checking for line number-specific options on
the node [3][4]. This effectively prevents `linenothreshold` from being
used.
To allow `linenothreshold` to be used in literal blocks, this commit
disables the explicit configuration `linenos` on a literal block
instance when the `CodeBlock` and `LiteralInclude` directives are
processed.
[1]: b35198d847
[2]: https://github.com/sphinx-doc/sphinx/blob/v1.8.1/sphinx/transforms/post_transforms/code.py#L95-L97
[3]: https://github.com/sphinx-doc/sphinx/blob/v1.8.1/sphinx/directives/code.py#L156-L157
[4]: https://github.com/sphinx-doc/sphinx/blob/v1.8.1/sphinx/directives/code.py#L442-L444
Signed-off-by: James Knight <james.d.knight@live.com>
helloworld:
- Return version metadata from extension
- Use 'reST' instead of 'rST'
- Don't use single backticks
todo:
- Return version metadata from extension
- Link to events section of API guide, rather than entire document
- Include name of phases in when describing build phases
- Use more method cross-references where possible
- Fix typo in usage example
recipe:
- Return version metadata from extension
- Rework code to simplify things
- Remove docstrings from 'generate' functions, which are simply
duplicates of the original docstring
- Rename 'rcp' directive to 'recipe', the 'reref' role to 'ref', and a
whole lot of variables to something more grokable
- Fix typos in both documentation and code
I've also fixed up the docstrings for some of the 'domain' functions to
make them render a little nicer (they took me a while to figure out).
Signed-off-by: Stephen Finucane <stephen@that.guru>
