pdoc3/pdoc

Tables in `.. include::`ed markdown files merge with remaining docstring

howamith opened this issue · 2 comments

howamith commented

Expected Behavior

When pulling in a markdown table via .. include:: reStructuredText directive, any remaining content within that docstring simply follows on after said table.
expected

Actual Behavior

The remaining content gets included within the table from the .. include::ed markdown table.

actual

Steps to Reproduce

  1. Extract the contents of pdoc3-test.zip and open a terminal within the top level directory.
  2. Install pdoc3 if it isn't already installed. I was using pdoc3 in a venv when I discovered this, but I'd imagine having it installed globally won't affect things.
  3. Run pdoc --html --output-dir doc package --force
  4. Observe doc/package/index.html. You'll notice that everything in the top-level docstring from package/init.pyafter the.. include::ed markdown table from package/table.md` is included in the rendered table, as opposed to after the table, as expected.

Additional info

  • pdoc version: discovered in 0.9.2, also present in 0.10.0.
  • Workaround: add an empty HTML tag of some form (tested with span) after the table.
kernc commented

From the top of the head, I think this regex that extracts reST directives:

pdoc/pdoc/html_helpers.py

Lines 325 to 328 in 4aa70de

substitute = partial(re.compile(r'^(?P<indent> *)\.\. ?(\w+)::(?: *(.*))?'
r'((?:\n(?:(?P=indent) +.*| *$))*)', re.MULTILINE).sub,
partial(_ToMarkdown._admonition, module=module,
limit_types=limit_types))

might "eat up" all the trailing newlines, and therefore the content following appears to be attached to its previous paragraph without a clear break.

Can you check whether adding a suffix "\n" (or two) here resolves the issue?

pdoc/pdoc/html_helpers.py

Lines 278 to 281 in 4aa70de

if type == 'include' and module:
try:
return _ToMarkdown._include_file(indent, value,
_ToMarkdown._directive_opts(text), module)

Care to do a PR?

howamith commented

Adding a single "\n" to the end of what _ToMarkdown._include_file() returns does indeed fix the issue :)

Yes, happy to submit a PR!