Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Postprocess Sphinx Docstrings to make bullet lists use sane indentation. #19

Open
Erotemic opened this issue Jul 31, 2024 · 0 comments
Open

Comments

@Erotemic
Copy link
Owner

Issue originally documented in ubelt: Erotemic/ubelt#159

But the problem occurs in multiple repos. Basically when sphinx gets this:

The following is a glossary of terms and jargon used in this repo.

* callname - the name of a callable function, method, class etc... e.g.
  ``myfunc``, ``MyClass``, or ``MyClass.some_method``.

* got / want - a test that produces stdout or a value to check. Whatever is
  produced is what you "got" and whatever is expected is what you "want".
  See :mod:`xdoctest.checker` for more details.

* directives - special in-doctest comments that change the behavior of the
  doctests at runtime. See :mod:`xdoctest.directive` for more details.

* chevrons - the three cheverons (``>>> ``) or right angle brakets are the
    standard prefix for a doctest, also referred to as a PS1 line in the
    parser.

* zero-args - a function that can be called without any arguments.

* freeform style - This is the term used to refer to a doctest that could be
    anywhere in the docstring. The alternative are structured doctests where
    they are only expected in known positions like in "Example blocks" for
    google and numpy style docstrings.

* TODO - complete this list (Make an issue or PR if there is any term you don't
    immediately understand!).

Which looks nice because there is an indent after the bullet so it is easier for the eyes to find the bullets.

But it produces this junk:

image

We just need to remove the newline and indent so sphinx sees it all on the same line, but let the code break it up.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant