2

I have a written a program in Python 3 and are using Sphinx to document it. Sphinx's autodoc is great, however it only works with Python 2. Some modules work fine in autodoc, however modules don't. Some examples: Python 2 complains about Python 3 style metaclasses, and some modules which don't exist anymore in Python 2 such as configparser. This is annoying as it cannot import the docstrings from that file.

I don't want to rewrite the whole program in Python 2, however I want to use autodoc.

One idea I had was a small program that read each Python file and removed all functionality but just left the basic function and classes with their docstrings (because autodoc imports each module and reads the docstring of a specific function or class).

import configparser
import os

class TestClass:
    """
    I am a class docstring.
    """
    def method(self, argument):
        """
        I am a method docstring.
        """
        #Some code here
        print(os.getcwd())

def TestFunction():
    """
    I am a function docstring.
    """
    #Some more useless code here
    return os.path.join("foo", "bar")

into...

class TestClass:
    """
    I am a class docstring.
    """
    def method(self, argument):
        """
        I am a method docstring.
        """
        pass

def TestFunction():
    """
    I am a function docstring.
    """
    pass

In this way the processed code can be read by autodoc, but still have the docstrings which is what I really need. Is this the best way of going about this, and does anyone have any suggestions as to how to write the little program which converts the code.

I can remove the metaclass problem very easily with some regular expressions, but I am struggling with the rest.

m = re.search("\(metaclass=.*\)", file_content)
if m:
    file_content = "".join(file_content[:m.start()], file_content[m.end():])

Would the ast module be useful?

Thanks.

mzjn
  • 48,958
  • 13
  • 128
  • 248
Giacomo
  • 412
  • 3
  • 10

3 Answers3

5

You can just install the development version of sphinx, which supports python 3.

pip-3.2 install hg+https://bitbucket.org/birkenfeld/sphinx

I tested the autodoc feature on your class and it worked.

Florin Cartarescu
  • 98
  • 5
1

What tends to be the solution is sprinkling try/except clauses in your code.

Python 2.6 has configparser but it is known as ConfigParser (python 3 changed the camelcase names to all lower case)

so something like:

try:
  import configparser
except ImportError:
  #we are in 2.x
  import ConfigParser as configparser

you might want to do a few things like this where it's broken. between the two. metaclasses though between the two I'm not sure to handle.

Mike Ramirez
  • 10,750
  • 3
  • 26
  • 20
  • 1
    True this would work... but I don't really want to go through all of my code just to fix a problem with autodoc. That's effectively porting my program to both Python 2 and 3! What I really need is a small (I hope!) script to process the code to a form that autodoc can import without any problems. Thanks anyway. – Giacomo Apr 09 '11 at 19:26
  • Two things, Paul's answer is probably what want, creating a python 3 only version limits the usage of your app. Not everyone is using python 3 as some libs haven't been ported yet. Until python 3 is more mainstream, writing compatible code between 2.x and 3.x is the most optimal solution. – Mike Ramirez Apr 09 '11 at 20:17
0

There's a 3to2 library that can convert Python 3 code to python 2. You could try this in conjunction with Sphinx.