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

I’ve looked into the docstrings and how they are r...

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.

fresh-cat-90827

07/12/2021, 9:58 PM

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?

happy-kitchen-89482

07/12/2021, 9:59 PM

Hmm, yeah, this whole thing is pretty fragile wrt quoting

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

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

happy-kitchen-89482

07/12/2021, 10:01 PM

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

🙏 1

happy-kitchen-89482

07/12/2021, 10:01 PM

Thanks for the headsup

💯 1

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.

Open in Slack

Previous Next