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.12k stars 145 forks source link

Leave trailing line break in reST directives #385

Closed howamith closed 2 years ago

howamith commented 2 years ago

Closes #384.

Feels a little clunky adding a trailing line break when processing reST directives, to then have to remove it again for reST directives in code blocks, but I couldn't see any other way. Figured I'd submit a PR anyway for feedback and go from there.

howamith commented 2 years ago

Another possibly way of neatening this up would be to somehow detect the context of where the reST directive is (i.e whether or not it's within a code block) and only add the trailing new-line where appropriate. This context could be detected in, or outside of and passed in, to _ToMarkdown._admonition().

kernc commented 2 years ago

Another way would be to actually amend the culprit regex. It's posed as:

^(?P<indent> *)\.\. ?(\w+)::(?: *(.*))?
((?:\n(?:(?P=indent) +.*| *$))*)

for its second line to matche any indented paragraphs (separated with a line break). E.g.:

Outside admonition.

.. warning:: Title
   First paragraph.

   Second paragraph.  # Our regex matches this final line break. But if it didn't ...

Outside admonition.

As can be seen here (trailing \n is visible in the "Export Matches" JSON).

I think we could rewrite the regex to not consume the line break unless another indented paragraph follows it ... :thinking:

howamith commented 2 years ago

Not quite fully isolated to just changing the regex, but I think that's the closest you'll get (though I'm by no means an expert when it comes to regex!).

Let me know what you think - if you're happy with that then I'll squash the redundant commits and let you merge :)

kernc commented 2 years ago

Excellent find of the regex! Many thanks! :cake: