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?

Dubiety

See https://mcmap.net/q/1163917/-replacing-python-docstrings-closed. One wishes that user tomaz had provided some more details about his converter. Perhaps it's the same guy here: mail-archive.com/[email protected]/msg03159.html. – Stalder

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)

Stalder

Update: the sphinx-epytext extension provides basic Epytext support. See pypi.python.org/pypi/sphinx-epytext. – Stalder

sphinx-epytext worked really well for me. I have shared my experience with it. https://mcmap.net/q/1073393/-automated-way-to-switch-from-epydoc-39-s-docstring-formatting-to-sphinx-docstring-formatting – Mirepoix

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

Copernicus

I gave this a shot, but the patches created don't include the __doc__ string, and Epydoc markup like B{Some bold text} remains in the .patch files. Is that expected? – Soria

@Soria what do you mean by "don't include the doc string" ? Concerning Pyment it focuses on the tags not the inlike markup. But you can open an issue to manage it. – Copernicus

Ah, so fields from section 2.6 of epydoc.sourceforge.net/epytext.html would be converted, but not anything inline (from sections 3 through 3.4)? – Soria

@Soria that's it. So as I said you can request it by opening an issue on Github. And what about your __doc__ question ? – Copernicus

No questions now. If module.__doc__ isn't processing inline markup, it's because the feature is not supported. Thanks! – Soria

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.

Rattan

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.

Mirepoix