12

I have a utils module in my package. It consists of several misc standalone methods that do not require instantiation.

I would like to place some generic comments/docstring inside this utils file, such as:

import os
import json

"""
Miscellaneous methods that help in <<blah blah>>
Does not require explicit instantiation.

The following actions can be performed:
===============   ===============
Action            Method
===============   ===============
Get a             :meth:`methoda`
Get b             :meth:`methodb`
"""

def methoda(data):
    "Gets A ..."
    ...

def methodb(data):
    "Gets B ..."
    ...

As seen above, the docstring has a table including links to the individual methods. Currently, my index.rst has this part to include utils:

Utilities
============
.. automodule:: packagename.utils
   :members:

Currently, I get the docstrings of the individual methods properly displayed in the documentation, but not the top-level docstring of the module (outside of any class or method). What is the best way to have have sphinx include the above?

One option might be to move the top-level docstring outside of this file, such as to index.rst etc. But I would prefer not doing this, and retain it within the source file.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Shailesh Appukuttan
  • 770
  • 8
  • 19
  • 9
    That *isn't* the top-level docstring. It's just a string literal that doesn't have an identifier, it will be dereferenced immediately. To be added as the `__doc__` of the module (so Sphinx can see it) it must be the first statement in the module; move it above the import statements. See [PEP-257](https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring). – jonrsharpe Nov 02 '17 at 09:40

1 Answers1

8

Thanks to jonsharpe for his comment, and leading me to the proper way of doing this.

For future reference by others, I basically moved the docstrings to the start of the file:

"""
Miscellaneous methods that help in <<blah blah>>
Does not require explicit instantiation.

The following actions can be performed:
===============   ===============
Action            Method
===============   ===============
Get a             :meth:`methoda`
Get b             :meth:`methodb`
"""

import os
import json

def methoda(data):
    "Gets A ..."
    ...

def methodb(data):
    "Gets B ..."
    ...

And that's it! Everything works.

Shailesh Appukuttan
  • 770
  • 8
  • 19