I'm using the Sphinx autodoc extension to document a module, and I'd like to get a flat list of the module's members in the documentation output.
I tried using the following:
.. automodule:: modname
:members:
However, there are two problems with this:
It includes the module's docstring, which I don't want here.
The name of each entry is prefixed with "modname.", which is completely redundant (since this page is specifically for documenting this module)
However, I haven't been able to find any config options that would let me selectively disable these two aspects while still getting the automatic listing of all of the module members.
My current plan is to just use autofunction (etc) and explicitly enumerate the members to be documented, but I'd still like to know if I missed an easy way to achieve what I originally wanted.
Update: I at least found a workaround for the second part: set add_module_names=False in conf.py. That's a global setting though, so it doesn't really answer my original question.
Looking at this answer to a similar question, I've found that you can use the autodoc-process-docstring event to remove the docstrings from modules appending the following code to your conf.py:
def skip_modules_docstring(app, what, name, obj, options, lines):
if what == 'module':
del lines[:]
def setup(app):
app.connect('autodoc-process-docstring', skip_modules_docstring)
Note that the del statement is needed because, according to the documentation, the modification to lines must happend in place (it you create a new object, it doesn't work).
Finally, you can also use name to filter the docstrings of just a few modules while keeping the ones from others.
Related
I have a module mod with some submodule submod and use .. automodule:: mod.submod to generate documentation for it.
The signatures of the elements (functions, classes etc.) in the modules now show the qualified name, like mod.submod.my_function(*args, **kwargs).
I would instead like Sphinx to just show the name of the function, i.e. the signature my_function(*args, **kwargs).
Do I have any way to drop the leading module and submodules in the signature?
Omitting module and package names preceding functions, methods and variables is done by setting the add_module_name configuration in your conf.py:
add_module_names = False
This is not obvious because of the numerous autodoc configurations that together with the sphinx-napoleon configurations make you expect the configuration elsewhere.
Yes, try this in docs/mod/submod.rst:
.. automodule:: mod.submod
.. autofunction:: my_function
See example HTML build and reST source in Pyramid documentation.
Bonus: see the Sphinx docs for Cross-referencing syntax:
If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:~Queue.Queue.get will refer to Queue.Queue.get but only display get as the link text.
I have a Python app with many modules. There's a YAML config file which contains configuration settings for each module. In each module's init(), I load the config and then process it into a config dictionary for that module.
The processing is ugly right now. Dozens and dozens of lines at the beginning of each module with a lot of stuff like:
if 'foo' not in config:
config['foo'] = bar
or
if 'foo' in config:
config['foo'] = string_to_list(config['foo'])
else:
config['foo'] = list()
etc.
So now I want to write a centralized config processing method that each module can use. I'm thinking that I want to use a YAML-formatted string to specify what the final config should look like. (Which settings are mandatory, default values, object types, etc.)
I'm thinking the config specification in each module could be something like this: (with the type|default|required values)
config_template = """MySection:
setting1: int|0
setting2: string|None|required
setting3: int|10"""
So far, so good. My real question is whether there's any way for me to save this config specification thing in each module in a docstring for init() or something. I'm thinking that since I'm essentially defining exactly what the module expects for its config, along with the defaults and the types, if I could store this config thing in the docstring then I ought to be able to write something and/or configure sphinx to pretty it up for the documentation?
So I wonder if this approach sounds sane in general, and, if so, is there a way I can store this config info in the docstring to get it to work as double duty?
EDIT: I considered setting up a dictionary with default values first, and certainly that will take care of the defaults. But there are a lot of cases where I need the values to be of a certain type. For example, maybe some have to be a list, but if a single item is entered into the config file it will be read as a string, so I need the config processor to convert the string to a list with that string as its only item.
EDIT 2: The reason I was asking about the docstring is because I was thinking that my config specification would essentially tell a programmer what this modules was expecting in terms of a config dictionary, so if I can do it in the docstring then I can just specify it once and have the module use it for its config as well as have it appear in the sphinx documentation. But if that's not possible, then so be it. I can use it in a variable (like in my example above) and then write the docstring manually.
Thanks!
Brian
I'm currently documenting a whole module with autodoc. However, I define several variables on the module level that contain long lists or dicts. They are included in the documentation together with the values, and the values are unformatted, so it looks like a 10-lines mess. What I want is for the docstring of those variables to be included, but for the values to be omitted or at least nicely formatted.
I've tried to exclude the variable from automodule directive and add it like that:
.. automodule:: foo.bar
:members:
:exclude-members: longstuff
.. py:data:: longstuff
This resulted in that only the variable name was included, whereas both the docstring and the value of longstuff were not present in the documentation.
How can I keep the docstring and get rid of the value (or have it nicely formatted) at the same time?
There is no simple configuration setting for omitting values of module level variables in the output. But you can do it by modifying the DataDocumenter.add_directive_header() method in autodoc.py. The crucial line in that method is
self.add_line(u' :annotation: = ' + objrepr, '<autodoc>')
where objrepr is the value.
The following monkey patch added to conf.py works for me:
from sphinx.ext.autodoc import ModuleLevelDocumenter, DataDocumenter
def add_directive_header(self, sig):
ModuleLevelDocumenter.add_directive_header(self, sig)
# Rest of original method ignored
DataDocumenter.add_directive_header = add_directive_header
Other than for __init__.py files, do the leading and trailing double underscores have any significance in a file name? For example, is __model__.py in any way more significant than model.py?
Double underscores in filenames other than __init__.py and __main__.py have no significance to Python itself, but frameworks may use them to indicate/identify various things.
Ahhh! I see you've discovered magic methods.
The double underscores are called "dunder" and they invoke special methods which can have some really neat effects on objects. They don't change significance, but they are pretty amazing voodoo, and a good tool to have on your belt.
Here's a link of many links, I learned all about magic methods through here.
http://pythonconquerstheuniverse.wordpress.com/2012/03/09/pythons-magic-methods/
__init__ is a magic method for declaring stuff to happen on initialization of an object. It only preceded by __new__.
The most useful of these methods I've been using is the __dict__ method. The __dict__ method makes it so that all attributes in a class turn into key value pairs that can then be used like a dictionary. Although I don't think using it as a file name would be useful.
here's an example:
class Thing(object):
def __init__(self): ##Init here is a magic method that determines what haps first
self.tint = "black"
self.color = "red"
self.taste = "tangy"
thing = Thing()
dictionary_from_class = {}
for key in thing.__dict__.keys(): ##returns all key values. here: "tint, color, taste"
dictionary_from_class[key] = thing.__dict__[key]
Fire up Idle in python, and try that out. Good luck in practicing python voodoo!
EDITED
Sorry, I really quickly read your question, let me mention this because I may have not covered it in my answer: If the filename is __init__.py, it does a similar thing, to what I mention before. It invokes the Initialization, and python will do that stuff as soon as the folder is reached for module usage. That is if you are reading off that file because it was called, such as referring to a folder of modules, and in that case you NEED a __init__.py file just to get python to recognize it inside the folder. You can use any of the magic methods as names to get a similar functionality upon usage.
I hope that clarification was useful.
-Joseph
That's it. If you want to document a function or a class, you put a string just after the definition. For instance:
def foo():
"""This function does nothing."""
pass
But what about a module? How can I document what a file.py does?
Add your docstring as the first statement in the module.
"""
Your module's verbose yet thorough docstring.
"""
import foo
# ...
For packages, you can add your docstring to __init__.py.
For the packages, you can document it in __init__.py.
For the modules, you can add a docstring simply in the module file.
All the information is here: http://www.python.org/dev/peps/pep-0257/
Here is an Example Google Style Python Docstrings on how module can be documented. Basically there is an information about a module, how to execute it and information about module level variables and list of ToDo items.
"""Example Google style docstrings.
This module demonstrates documentation as specified by the `Google
Python Style Guide`_. Docstrings may extend over multiple lines.
Sections are created with a section header and a colon followed by a
block of indented text.
Example:
Examples can be given using either the ``Example`` or ``Examples``
sections. Sections support any reStructuredText formatting, including
literal blocks::
$ python example_google.py
Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.
Attributes:
module_level_variable1 (int): Module level variables may be documented in
either the ``Attributes`` section of the module docstring, or in an
inline docstring immediately following the variable.
Either form is acceptable, but the two should not be mixed. Choose
one convention to document module level variables and be consistent
with it.
Todo:
* For module TODOs
* You have to also use ``sphinx.ext.todo`` extension
.. _Google Python Style Guide:
http://google.github.io/styleguide/pyguide.html
"""
module_level_variable1 = 12345
def my_function():
pass
...
...
You do it the exact same way. Put a string in as the first statement in the module.
It's easy, you just add a docstring at the top of the module.
For PyPI Packages:
If you add doc strings like this in your __init__.py file as seen below
"""
Please refer to the documentation provided in the README.md,
which can be found at gorpyter's PyPI URL: https://pypi.org/project/gorpyter/
"""
# <IMPORT_DEPENDENCIES>
def setup():
"""Verify your Python and R dependencies."""
Then you will receive this in everyday usage of the help function.
help(<YOUR_PACKAGE>)
DESCRIPTION
Please refer to the documentation provided in the README.md,
which can be found at gorpyter's PyPI URL: https://pypi.org/project/gorpyter/
FUNCTIONS
setup()
Verify your Python and R dependencies.
Note, that my help DESCRIPTION is triggered by having that first docstring at the very top of the file.