search

pdoc3 / pdoc

:snake: :arrow_right: :scroll: Auto-generate API documentation for Python projects
https://pdoc3.github.io/pdoc/
GNU Affero General Public License v3.0
1.14k stars 146 forks source link

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

Closed howamith closed 2 years ago

howamith commented 2 years ago

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 frompackage/init.pyafter the.. include::ed markdown table frompackage/table.md` is included in the rendered table, as opposed to after the table, as expected.

Additional info

kernc commented 2 years ago

From the top of the head, I think this regex that extracts reST directives: https://github.com/pdoc3/pdoc/blob/4aa70de2221a34a3003a7e5f52a9b91965f0e359/pdoc/html_helpers.py#L325-L328 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? https://github.com/pdoc3/pdoc/blob/4aa70de2221a34a3003a7e5f52a9b91965f0e359/pdoc/html_helpers.py#L278-L281 Care to do a PR?

howamith commented 2 years ago

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

Yes, happy to submit a PR!