Skip to content

Sphinx documentation incorrect formatting. #159

@Erotemic

Description

@Erotemic

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

Metadata

Metadata

Assignees

Labels

documentationIssues related to documentation / formatting

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions