https://pantsbuild.org/ logo
#development
Title
# development
f

fresh-cat-90827

07/12/2021, 9:54 PM
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.
Having this code in the
subsystem.py
:
Copy code
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
Copy code
<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`, `&#x27;test&#x27;`, `(test)`, &quot;`test`&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: `&#x27;test&#x27;`
Double quote: `&quot;test&quot;`</p>
</div>
<br>
which is drawn as on the image attached. Bringing the two line breaks before the docstring would solve the problem:
Copy code
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?
h

happy-kitchen-89482

07/12/2021, 9:59 PM
Hmm, yeah, this whole thing is pretty fragile wrt quoting
f

fresh-cat-90827

07/12/2021, 10:00 PM
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
h

happy-kitchen-89482

07/12/2021, 10:00 PM
There is a delicate interplay between raw text, HTML and markdown and it's not obvious what the right thing to do is.
2
I'll take a look and see if we can be more rigorous
🙏 1
Thanks for the headsup
💯 1
f

fresh-cat-90827

07/12/2021, 10:06 PM
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.