pythonpython-sphinxautodoc

Including docstring in Sphinx Documentation


I'd like to include just the docstring of a specific function in my Sphinx documentation. However there seem to be no options to just display these details without associated class and function definitions using http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

I've tried creating a class as outlined in Show *only* docstring in Sphinx documentation? but I'm not sure how this fits in with the templating.

I've also tried the autodoc-process-docstring event handler with no luck.

So rather than my documentation displaying (as it is currently):

class module.MyClass(param)

    This is the class doc string

    my_method()

        This is my method doc string

I just want to display:

This is my method doc string

My current template in a .txt file is:

.. autoclass:: module.MyClass
    :members: my_method

Solution

  • After looking through the source and experimenting - here is how to do it in Sphinx 1.1.

    In your conf.py file create a new MethodDocumenter subclass. Here you can set a new "objtype", make sure the docstring is not indented, and remove the title.

    from sphinx.ext import autodoc
    
    class SimpleDocumenter(autodoc.MethodDocumenter):
        objtype = "simple"
    
        #do not indent the content
        content_indent = ""
    
        #do not add a header to the docstring
        def add_directive_header(self, sig):
            pass
    

    Then make sure this is added to the available documenters with the following function (again in conf.py):

    def setup(app):
        app.add_autodocumenter(SimpleDocumenter)
    

    Then when you just want to display a method's docstring use the following format in your .txt or .rst files. Just prefix your objname with auto.

    .. autosimple:: mod.MyClass.my_method