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

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.