Erotemic / ubelt

A Python utility library with a stdlib like feel and extra batteries. Paths, Progress, Dicts, Downloads, Caching, Hashing: ubelt makes it easy!
Apache License 2.0
719 stars 43 forks source link

Sphinx documentation incorrect formatting. #159

Open Erotemic opened 1 month ago

Erotemic commented 1 month ago

While the ubelt documentation has gotten much better and cleaner, there are still locations where what makes documentation look good in the code results in documentation that looks bad in sphinx. I'm making this issue so when I see one of those locations I can mark it. The goal is to write a sphinx plugin that can detect and fix these issues so documentation can look good in both the raw docstrings inside the code itself as well as when sphinx renders it.

The first offending location is in ubelt.util_path.Path, where the following docstring:

    Modified methods are

        * :py:meth:`ubelt.Path.touch` - returns self to support chaining

        * :py:meth:`ubelt.Path.chmod` - returns self to support chaining and
            now accepts string-based permission codes.

results in:

image

The last bullet should not have any bold and should not be on separate lines. A preprocessor should detect this and group the line.

This is in version 1.3.6, but it looks like read-the-docs previous versions are not working atm, so that is another issue, but here is a link to the latest: https://ubelt.readthedocs.io/en/latest/auto/ubelt.util_path.html#ubelt.util_path.Path

Erotemic commented 1 month ago

Also occurs in xdoctest (1.1.5 branch, manually fixed in 1.1.6). Original docstring was:

* 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!).

This is more of an xcookie issue as that needs to generate the postprocessing we do in docs/source/conf.py