Python – sphinx-apidoc usage – multiple source python directories

pythonpython-sphinxsphinx-apidoc

So I have my python source files in two different directories:-

e.g.

~/work/myproject
~/.virtualenvs/myproject

How do I use sphinx-apidoc to look in both directories recursively to generate my reST files?

Obviously,

sphinx-apidoc -o docs/source ~/work/myproject

works perfectly fine but when I attempt to run

sphinx-apidoc -o docs/source ~/.virtualenvs/myproject

again, sphinx tells me that "docs/source/modules.rst already exists, skipping" which of course is true as I have already run sphinx-apidoc once to generate it.

So how do I execute it once and search in both directories?

Best Answer

According to the Sphinx apidoc documentation, the commandline syntax is:

sphinx-apidoc [options] -o <outputdir> <sourcedir> [pathnames ...]

Update: wrong, see comment by @jgbarah below.

This means that if you want to document sources in two separate directories, you can pass both directories/pathnames at once, so something like:

sphinx-apidoc -o docs/source ~/work/myproject ~/.virtualenvs/myproject

Improved suggestion:

You could make a subdirectory inside your documentation per project. So something like:

sphinx-apidoc -o docs/source/app1 ~/work/myproject1
sphinx-apidoc -o docs/source/app2 ~/work/myproject2

With a toctree you could then point at the two subdirectories:

.. toctree::
    :maxdepth: 2

    app1/index.rst
    app2/index.rst

Related Solutions

Python – a clean, Pythonic way to have multiple constructors in Python

Actually None is much better for "magic" values:

class Cheese():
    def __init__(self, num_holes = None):
        if num_holes is None:
            ...

Now if you want complete freedom of adding more parameters:

class Cheese():
    def __init__(self, *args, **kwargs):
        #args -- tuple of anonymous arguments
        #kwargs -- dictionary of named arguments
        self.num_holes = kwargs.get('num_holes',random_holes())

To better explain the concept of *args and **kwargs (you can actually change these names):

def f(*args, **kwargs):
   print 'args: ', args, ' kwargs: ', kwargs

>>> f('a')
args:  ('a',)  kwargs:  {}
>>> f(ar='a')
args:  ()  kwargs:  {'ar': 'a'}
>>> f(1,2,param=3)
args:  (1, 2)  kwargs:  {'param': 3}

http://docs.python.org/reference/expressions.html#calls

Python – Dealing with multiple Python versions and PIP

The current recommendation is to use python -m pip, where python is the version of Python you would like to use. This is the recommendation because it works across all versions of Python, and in all forms of virtualenv. For example:

# The system default python:
$ python -m pip install fish

# A virtualenv's python:
$ .env/bin/python -m pip install fish

# A specific version of python:
$ python-3.6 -m pip install fish

Previous answer, left for posterity:

Since version 0.8, Pip supports pip-{version}. You can use it the same as easy_install-{version}:

$ pip-2.5 install myfoopackage
$ pip-2.6 install otherpackage
$ pip-2.7 install mybarpackage

EDIT: pip changed its schema to use pipVERSION instead of pip-VERSION in version 1.5. You should use the following if you have pip >= 1.5:

$ pip2.6 install otherpackage
$ pip2.7 install mybarpackage

Check https://github.com/pypa/pip/pull/1053 for more details

References:

Best Answer

Related Solutions

Python – a clean, Pythonic way to have multiple constructors in Python

Python – Dealing with multiple Python versions and PIP

Related Topic