CODEWITHSUNDEEP
pythonpython-sphinxautodoc
geographika
geographika

Reputation: 6528

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

Upvotes: 9

Views: 4193

Answers (2)

Sigmatics
Sigmatics

Reputation: 793

I used this approach with Sphinx 5.3.

If you don't want to override the default MethodDocumenter for your class API documentation, you need to also override the following can_document_member and set it to False. The resulting class looks as follows

class SimpleDocumenter(autodoc.MethodDocumenter):
"""
Reference a class or method docstring only.
see https://stackoverflow.com/a/7832437/5726546
"""
  objtype = "simple"

    content_indent = ""

    @classmethod
    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
        return False

    # do not add a header to the docstring
    def add_directive_header(self, sig: str) -> None:
        pass

Setup and directive are the same as in the answer by geographika.

Upvotes: 0

geographika
geographika

Reputation: 6528

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

Upvotes: 15

Related Questions