Problem Description
Example blocs inside docstrings can be tested to check they don’t contain mistakes, such special tests are named doctests. Python allows doctests to contain options, passed as directives, to modify the evaluation of the test. By instance:
>>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
[0, 1, ..., 18, 19]
where +ELLIPSIS enables ... to be used as a regex .*, and +NORMALIZE_WHITESPACE makes spaces not accounted for in the evaluation.
Directives are convenient for writing doctests, but are not useful in a documentation.
Proposal
I suggest to filter doctest directives out in the outputed HTML document. Given that directives are always formated as # doctest: <something>, I think it would be fairly easy to identify them with a regex. This behavior could be modified by a pdoc option, such as --keep-doctests-directives.
What do you think?
Problem Description
Example blocs inside docstrings can be tested to check they don’t contain mistakes, such special tests are named doctests. Python allows doctests to contain options, passed as directives, to modify the evaluation of the test. By instance:
where
+ELLIPSISenables...to be used as a regex.*, and+NORMALIZE_WHITESPACEmakes spaces not accounted for in the evaluation.Directives are convenient for writing doctests, but are not useful in a documentation.
Proposal
I suggest to filter doctest directives out in the outputed HTML document. Given that directives are always formated as
# doctest: <something>, I think it would be fairly easy to identify them with a regex. This behavior could be modified by apdocoption, such as--keep-doctests-directives.What do you think?