I ve looked into the docstrings and how they are rendered in

Question

I ve looked into the docstrings and how they are rendered into the documentation using ` pants run build support bin generate docs py` It looks like the rendering is broken I ve spent hours debugging the HTML rendering in the `pystache` <https github com pantsbuild pants blob main build support bin generate docs py L410> and have only been able to identify a pattern

fresh-cat-90827 · Answer

Having this code in the `subsystem py` ``` register dummy arg type=bool default=True advanced=True help= Sample test strings `test` ` test` ` test` ` test` ` test ` ` test ` `test` The values here are broken But here are two line breaks n n And now all is good `test` ` test` ` test` ` test` ` test ` n But n n Single quote ` test ` n Double quote ` test ` ``` and running the ` pants run build support bin generate docs py` gives ` md` ``` lt div style= color purple gt lt h3 gt lt code gt dummy arg lt code gt lt h3 gt lt code gt no yapf dummy arg lt code gt lt br gt lt code gt PANTS YAPF DUMMY ARG lt code gt lt br gt lt div gt lt div style= padding left 2em gt lt span style= color green gt default lt code gt True lt code gt lt span gt lt p gt Sample test strings `test` ` test` ` test` ` test` ` amp x27 test amp x27 ` ` test ` amp quot `test` amp quot The values here are broken But here are two line breaks And now all is good `test` ` test` ` test` ` test` ` test ` But Single quote ` amp x27 test amp x27 ` Double quote ` amp quot test amp quot ` lt p gt lt div gt lt br gt ``` which is drawn as on the image attached Bringing the two line breaks before the docstring would solve the problem ``` help= n nSample test strings `test` ` test` ` test` ` test` ` test ` ` test ` `test` ``` I see that pattern everywhere in the docs the first section of the docstring that goes before the ` n n` fails to render the markdown properly and whatever comes after that in a new paragraph is rendered fine except the code that has inside single or double quotes it s broken no matter what unless the README s Markdown rendering mechanisms handle them differently to a mechanism used by handful of different applications I ve tried locally < happy kitchen 89482> I believe you ve been writing the docstrings rendering code recently maybe you have some ideas where to dig further if you have it fresh in your memory

happy-kitchen-89482 · Answer

Hmm yeah this whole thing is pretty fragile wrt quoting

fresh-cat-90827 · Answer

to be fair the `` test `` is quite unusual pattern so it s lower prio than having markdown code drawn properly only if after a couple of breaking lines

happy-kitchen-89482 · Answer

There is a delicate interplay between raw text HTML and markdown and it s not obvious what the right thing to do is

happy-kitchen-89482 · Answer

I ll take a look and see if we can be more rigorous

happy-kitchen-89482 · Answer

Thanks for the headsup

fresh-cat-90827 · Answer

thank you < happy kitchen 89482> This is low prio of course Once we have this sorted I can start my sweeping through the docstrings fixing missing ``` symbols to make things tidy thought being able to draw the docs with a proper support for code snippets locally would help