Support auto-generated API docs

[radix]

I use sphinx-apidoc to auto-generate API documentation for my project. Right now I have to commit these auto-generated files to my repository so that RTD can build them into HTML docs. It'd be cool if RTD could run sphinx-apidoc for me, since it's easy to forget to regen API docs and commit them to my repo after making changes to my code.

[radix]

fwiw I'd also be happy if RTD just allowed me to specify my own build process, so it wouldn't to specifically hardcode support for sphinx-apidoc. Though that may also be difficult to allow in a secure way.

[sontek]

I'm also trying to use sphinx-apidoc for my documentation. I use a tox -e docs to generate my docs

[jantman]

+1 on this... I'm sure, even documenting it in the release procedure, that I'll forget to generate the apidocs and commit them...

[gregmuellegger]

We are currently developing a new build system. And I assume we could integrate this in there somehow. However it's not there yet, so I assume we won't have a fix for this in the next couple of weeks, but more in the terms of months.

[rtveitch]

+1

Adding this support would be incredible and would significantly reduce the friction associated with keeping documentation current. If sphinx-apidoc was supported in readthedocs, a developer wouldn't even need the sphinx toolchain installed locally if they didn't want; their only responsibility would be to keep docstrings up to date.

[matteobachetti]

+1

[posita]

👍

[msarahan]

+1

[jsmedmar]

+1

[alyjak]

FYI, you can work around this by adding something like the following to your project's conf.py file:

def run_apidoc(_):
    modules = ['a_list_of',
               'python_module_directories',
               'in_your_project']
    for module in modules:
        cur_dir = os.path.abspath(os.path.dirname(__file__))
        output_path = os.path.join(cur_dir, module, 'doc')
        cmd_path = 'sphinx-apidoc'
        if hasattr(sys, 'real_prefix'):  # Check to see if we are in a virtualenv
            # If we are, assemble the path manually
            cmd_path = os.path.abspath(os.path.join(sys.prefix, 'bin', 'sphinx-apidoc'))
        subprocess.check_call([cmd_path, '-e', '-o', output_path, module, '--force'])

def setup(app):
    app.connect('builder-inited', run_apidoc)

This will run sphinx-apidoc during the builder-inited sphinx core event. It should work on readthedocs as well as locally, enabling you to autogenerate your api docs without having to store the output in your git repo. You can even cross reference your manual documentation with these API references.

[Maxyme]

Another solution which doesn't involve directly calling a subprocess is to use the following in conf.py:

from sphinx.apidoc import main
main(['-e', '-o', ...])

instead of

subprocess.check_call([cmd_path, '-e', '-o', output_path, module, '--force'])

This solved one of the issues I had was with long path names which are restricted on readthedocs.

[BowenFu]

@alyjak @Maxyme Thanks. And this works for me.

def run_apidoc(_):
    from sphinx.apidoc import main
    import os
    import sys
    sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
    cur_dir = os.path.abspath(os.path.dirname(__file__))
    module = '.'
    output_path = os.path.join(cur_dir, 'source')
    # main(['-e', '-o', output_path, module, '--force'])

def setup(app):
    app.connect('builder-inited', run_apidoc)

[TheChymera]

@BowenFu

Thank you! For your code to work, however, you would need to uncomment the main line. Not least of all, I found this incompatible with the directory structure I commonly see, where the .rst source files are all placed in the documentation directory (where config.py is also located). What worked for me was:

def run_apidoc(_):
	from sphinx.apidoc import main
	import os
	import sys
	sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
	cur_dir = os.path.abspath(os.path.dirname(__file__))
	module = os.path.join(cur_dir,"..","labbookdb")
	main(['-e', '-o', cur_dir, module, '--force'])

def setup(app):
	app.connect('builder-inited', run_apidoc)