Avoid bad Sphinx formatting of cement configuration

Question

We're using Sphinx to format our Python documentation, and cement to configure our CLIs. Unfortunately, Sphinx generates a lot of nonsensical output from cement configurations.

I've been unable to find any Sphinx directive or command line option to ignore the cement configuration that it should not format. We're using Sphinx 2.2.0, and sphinx-apidoc with options -f -P -o.

E.g., Sphinx formats this Python

class BaseController(cement.Controller):
    """ Base controller for command line application """

    class Meta:
        label = 'base'
        description = "Command line utilities for managing whole-cell model definitions"
        help = "Command line utilities for managing whole-cell model definitions"
        arguments = [
            (['-v', '--version'], dict(action='version', version=wc_lang.__version__)),
        ]

into this documentation

noisy documentation

The documentation shouldn't show the content of the Meta class. Can the Python be annotated with Sphinx directives to accomplish this?

@mzjn: thanks for letting me know; fixed with `?raw=1` suffix on Dropbox link. — Arthur, Sep 11 '19 at 19:20
I don't know anything about Cement. What exactly is "bad", "nonsensical" or "noisy"? The output you get looks similar to this, from the Cement docs: https://cement.readthedocs.io/en/portland/api/core/controller/. — mzjn, Sep 13 '19 at 09:09

score 0 · Answer 1 · answered Sep 14 '19 at 07:21

The documentation shouldn't show the content of the Meta class.

I presume that you have an automodule directive (generated by sphinx-apidoc) that looks something like this:

.. automodule:: wc_lang.__main__
   :members:
   :undoc-members:
   :show-inheritance:

The nested Meta class contains no docstrings, so it gets included on account of the :undoc-members: option. sphinx-apidoc adds this option by default.

To exclude Meta from the documentation, remove :undoc-members:. An alternative is to add :exclude-members: Meta.

Avoid bad Sphinx formatting of cement configuration

1 Answers1