Whitespaces in docstrings and Sphinx

[bdg221]

I am working on the calibration tables for the API docs that currently look like:

Is anybody familiar with a different/better way to have Sphinx retain whitespaces in a docstring?

I was able to get it working using:

This was the only way I was able to get it to work. The table has to be under Example: and the first line must start with >>>. This puts a <pre> tag around everything indented under Example.

Looking up more about how >>> is used, it turns out that it is part of doctest. While I don't think anybody is directly running calibrator.py (with or without the -v), it is a bit of a hacky-use in this situation. I did think about including the command lines that generate the table, but it gets a bit tricky. The log_results_flat() and log_results_cartesian() are applied to the results of running a calibrator which requires an executor and if we want the specific output in the docs, we would need custom settings. It does not make sense to me to put all of that in a docstring that's already pretty big due to the tables.

Anybody have any other ideas?

[purva-thakre]

You could use the list table directive in sphinx if the goal is to retain docstring formatting of a table.

[bdg221]

@purva-thakre Thanks for the suggestion. I tried playing around with list table and table directives. While I don't think those will apply to this, I did find that I can get the table to print correctly using :: (as long as it is not in the first line of the docstring.) So, by doing the following it works:

If flat form:: is at the end of the first line (even if the entire line is moved down), the formatting does not work since Sphinx sees it as a title of a section (notice how the sentence is bold.)

[purva-thakre]

@bdg221 Sphinx expects the table to be of a particular form.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables

The example docstring table in the function definition is copy-pasted from the function output directly where the formatting of columns/rows does not match with how sphinx expects you to format a table.

There are several options on how you can format a table for sphinx:

• https://myst-parser.readthedocs.io/en/latest/syntax/tables.html#markdown-syntax
• https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables

I just tried the following and it works as expected:

I am not too familiar with flatform::. I would say if that works, then go with the option that doesn't require a lot of work.

[bdg221]

The table in the docstring is an example of the output table, so it has to look exactly the same. This is more about needing Sphinx to retain whitespaces than print a table in a specific format.

[purva-thakre]

I understand what you are getting at. What I am trying to say is, with the way the table is added in the docstring, you can't use things like :align: left or :widths: 15 to set the whitespace. You might have to change the formatting to able to use the thing you want.

[purva-thakre]

@bdg221 What if you embed a screenshot of the table? This way you don't have to worry about formatting issues.

It also solves the problem of the table appearing exactly as that of the function output.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#images

ETA: As I said in the previous comment, since flatform:: works as well, I think that might be the easiest option as well.

[purva-thakre]

Closing as this appears to be fixed by #2568.

Feel free to reopen if we need to continue this discussion.