Automated way to switch from epydoc's docstring formatting to sphinx docstring formatting?

Question

I've got a project which I documented using epydoc. Now I'm trying to switch to sphinx. I formatted all my docstrings for epydocs, using B{}, L{} etc for bolding, linking and the like, and using @param, @return, @raise etc to explain input, output, exceptions and the likes.

So now that I'm switching to sphinx it loses all these features. Is there an automated way to convert docstrings formatted for epydocs to docstrings formatted for sphinx?

Answer 1

To expand on Kevin Horn's answer, docstrings can be translated on the fly in an event handler triggered by the autodoc-process-docstring event.

Below is a small demonstration (try it by adding the code to conf.py). It replaces the @ character in some common Epytext fields with :, which is used in the corresponding Sphinx fields.

import re

re_field = re.compile('@(param|type|rtype|return)') 

def fix_docstring(app, what, name, obj, options, lines):
    for i in xrange(len(lines)):
        lines[i] = re_field.sub(r':\1', lines[i])

def setup(app):
    app.connect('autodoc-process-docstring', fix_docstring)

Answer 2

Pyment is a tool that can convert Python docstrings and create missing ones skeletons. It can manage Google, Epydoc (javadoc style), Numpydoc, reStructuredText (reST, Sphinx default) docstring formats.

It accepts a single file or a folder (exploring also sub-folders). For each file, it will recognize each docstring format and convert it to the desired one. At the end, a patch will be generated to apply to the file.

To convert your project:

• install Pyment

Type the following (you can use a virtualenv):

$ git clone https://github.com/dadadel/pyment.git
$ cd pyment
$ python setup.py install

• convert from Epydoc to Sphinx

You can convert your project to Sphinx format (reST), which is the default output format, by doing:

$ pyment /my/folder/project

Answer 3

In theory you could write a Sphinx extension which would catch whatever event gets fired when a docstring gets read (source_read, maybe?) and translate the docstrings on the fly.

I say in theory because:

1. I've been meaning to write such a thing for a very long time, but haven't managed to get around to it yet.
2. Translating stuff like this is always harder than it seems.

You could also probably try just replacing all the docstrings in your code with a similar translator outside of Sphinx, perhaps using the ast module or something similar.

Answer 4

As one of the comment suggested, sphinx-epytext does provides the relevant support. How it worked for me:

Installing it is very easy:

pip install -U sphinx-epytext

It contains one file process_docstring.py that converts the epytext markups to reStructuredText markups by replacing @ with colon :.

Some of the fields I found missing in there were: ivar, var, cvar, vartype

Simply extend the existing list FIELDS in there:

FIELDS.extend(['ivar', 'var', 'cvar', 'vartype'])

Epytext understands @type for variables, but sphinx understands :vartype.

To fix that, replace the former ones with later ones inside process_docstring method.

Most of the syntax or docstring parts that Sphinx can't comprehend are reported as Warnings. You can log these warnings by running sphinx-build with -w <WarningLogFile>. As per my experience with it, Sphinx is very sensitive about how a field should start or end, missing-formatting-syntax, etc.