fresh-cat-90827
07/12/2021, 9:54 PM./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.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
<div style="color: purple">
<h3><code>dummy_arg</code></h3>
<code>--[no-]yapf-dummy-arg</code><br>
<code>PANTS_YAPF_DUMMY_ARG</code><br>
</div>
<div style="padding-left: 2em;">
<span style="color: green">default: <code>True</code></span>
<p>Sample test strings: `test`, `.test`, `/test`, `--test`, `'test'`, `(test)`, "`test`". The values here are broken. But here are two line breaks.
And now all is good: `test`, `.test`, `/test`, `--test`, `(test)`
But:
Single quote: `'test'`
Double quote: `"test"`</p>
</div>
<br>
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
07/12/2021, 9:59 PMfresh-cat-90827
07/12/2021, 10:00 PMhappy-kitchen-89482
07/12/2021, 10:00 PMfresh-cat-90827
07/12/2021, 10:06 PM