feature: autodoc: add :annotation: option for autodata and autoattribute

#109 Merged at bdb3fad
Deleted repository
autodoc_novalue (1c52b2fdfb26)
  1. Johannes Dewender

Current Situation

For data objects (module level) and attribute objects (class level) the autodoc extension prints the value/represenation if available.

.. autodata:: CD_DRIVE

can look like this:

CD_DRIVE = u'/dev/cdrom'
    some more text from the docstring

However, this might be unwanted because the value depends on the platform (and would be different on other platforms), is an object or just should not be relied on to have a certain value.

Proposed Feature

We introduce a novalue option, that keeps autodoc from value/representation output.

.. autodata:: CD_DRIVE

would look like this:

    some more text from the docstring

The option to prepend the module (or not) is not touched by this.


The pull-request implements this feature for autodata and autoattribute.

A documentation is also added. Since this is a new feature, this could be in the code for 1.2 the earliest. If it happens later, the documentation needs an update.

No additional tests are included. The test suite runs fine (2.6, 2.7, 3.3, du*). I did test this in a documentation of mine and it works great. It does what it should and no additional problems are created.

EDIT: :novalue: is now :annotation:, see below

Comments (17)

  1. Johannes Dewender author

    I also created a patch queue for these changes: sphinx-novalue (edit: link removed since that patch-queue is now deprecated)

    There is already an issue that requests a similar feature ("only fetch docstring"): #963

  2. Johannes Dewender author

    This might also be interesting for #904, where autoattributes having None as values seems to be a problem (and this is a workaround).

    See also https://groups.google.com/forum/?hl=en#!topic/sphinx-users/pgtUqkc8QBs and http://stackoverflow.com/questions/9153473/sphinx-values-for-attributes-reported-as-none/

    What's missing in this implementation is some type of recursive usage, like giving :novalue: as default or using it in .. automodule::/.. autoclass::. Enabling the use as a default should work in general (so you don't have to add it to every autodata), but that also won't work with using autoclass. I couldn't find out where the recursiveness of the defaults kick in or why it doesn't.

  3. Johannes Dewender author

    I got the test system to work (rm -r build helps) and after another fix on my side the test suite runs fine on my pull-request branch. It's a bit weird that the types for the options mismatch in the tests and in normal usage (util.struct vs autodoc.Options). That makes "novalue" in self.options work normally, but fail in the tests. I use self.option.novalue now.

  4. Jon Waltman

    Thanks for the working on this. It would be nice to have more control over how objects are displayed and I think an having option like this would help.

    While looking at your changes here, I got an idea for how to do this and also provide a more general way for displaying attributes. We just need to be able to specify the :annotation: option in the autodoc directives. eg:

    .. autodata:: userdir
    .. autodata:: userdir
    .. autodata:: userdir
       :annotation: = $HOME

    would be displayed as

    userdir = "/home/jon"
    userdir = $HOME

    It should be relatively straight forward to implement this, just add the annotation option for the two directives and use that value if it's provided instead of the generated one.

    I got the test system to work (rm -r build helps)

    The environment and doctree cache can get corrupted when making changes in the code. Deleting the build directory forces a fresh build.

    What's missing in this implementation is some type of recursive usage

    Yea, this is needed in a lot of other cases too. A general system for doing this on specific classes/modules/objects would be nice.


  5. Johannes Dewender author

    Implementing this as :annotation: is a good idea. That gives more possibilites.

    I will change my code so it does it like that and also address the "shared structure" issue.

  6. Johannes Dewender author

    I changed to :annotation: and implemented using an argument as the annotation if an argument is given. I created a SUPPRESS object to distinguish not having the :annotation: option set (-> None) and having no argument for :annotation: (-> SUPPRESS). (see annotation_option())

    tox2 runs fine with all versions of Python and Docutils except py25 and pypy (both not installed on my system currently, 1 test is skipped)

    I tested the functionality manually. All 3 cases checked for both :autodata: and :autoattribute:. (running sphinx on a project with a rst file that has these use cases and checking the "dirhtml" output)

  7. Johannes Dewender author

    I think the reason why this isn't moving forward is because 1.2 is in beta so no new features are currently accepted. There will hopefully be additional review when 1.2 is released.

  8. Georg Brandl repo owner

    It's rather that development itself has been a little slow. I'm not very strict on features during beta, so I'm merging it for beta2. Thanks for the contribution and the wait!

  9. Alex Buchanan

    I think this appends unsightly "None" annotations to "@Property" methods.

    I think I've traced that issue to the proper origin, at line 1145 of sphinx/ext/autodoc.py, you want to check if self.options.annotation is not None?

      1. Johannes Dewender author

        And I reproduced your fix, though this is not in 1145, but 1264 for me. Changed else to elif self.options.annotation is not None.

        @Georg Brandl : In what way should I present the fix? A new PR?

        I also still need to check out why exactly this works or didn't work before. Maybe the real problem is in the assignment of self.options.annotation somewhere.

      1. Alex Buchanan

        No problem.

        Sorry for the faux patch :D, i.e. "change this at this line", bitbucket and mercurial are foreign to me and I wanted to report the bug quickly without getting a format pull request figured out.