Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support auto-generated API docs #1139

Closed
radix opened this issue Feb 1, 2015 · 29 comments
Closed

Support auto-generated API docs #1139

radix opened this issue Feb 1, 2015 · 29 comments
Labels
Needed: documentation Documentation is required Needed: more information A reply from issue author is required

Comments

@radix
Copy link

radix commented Feb 1, 2015

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
Copy link
Author

radix commented Feb 1, 2015

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
Copy link

sontek commented Feb 10, 2015

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

@jantman
Copy link

jantman commented Jun 13, 2015

+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 gregmuellegger added the Improvement Minor improvement to code label Jul 10, 2015
@gregmuellegger
Copy link
Contributor

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.

@gregmuellegger gregmuellegger added this to the rtd-build milestone Jul 10, 2015
@ghost
Copy link

ghost commented Aug 7, 2015

+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
Copy link

+1

2 similar comments
@posita
Copy link

posita commented Oct 2, 2015

👍

@msarahan
Copy link

msarahan commented Oct 7, 2015

+1

@jsmedmar
Copy link

+1

@alyjak
Copy link

alyjak commented Feb 23, 2016

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.

fantix added a commit to decentfox/aioh2 that referenced this issue Mar 8, 2016
@Maxyme
Copy link

Maxyme commented Apr 29, 2016

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.

brahmlower added a commit to brahmlower/cssef that referenced this issue May 24, 2016
Turns out what I was going for isn't supported officially. There's a partial work around here (readthedocs/readthedocs.org#1139), but I haven't been able to get it working
brahmlower added a commit to brahmlower/cssef that referenced this issue Sep 5, 2016
I realized I had never actually tested the work around listed here: readthedocs/readthedocs.org#1139 I'm going to try that and see how it goes...
iMichka added a commit to CastXML/pygccxml that referenced this issue Oct 9, 2016
@BowenFu
Copy link

BowenFu commented Nov 10, 2016

@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
Copy link

TheChymera commented Jul 3, 2017

@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)

speller26 added a commit to amazon-braket/amazon-braket-default-simulator-python that referenced this issue Aug 14, 2020
Fixed previously failing Read the Docs builds by:
1. Explicity adding `method` and `path` to .readthedocs.yml; this was causing builds to fail altogether
2. Using [sphinxcontrib-apidoc](https://github.com/sphinx-contrib/apidoc) instead autodoc directly (see readthedocs/readthedocs.org#1139). Defore, our `tox -e docs` command would run `aphinx-apidoc` then `sphinx-build`. However, Read the Docs only runs `sphinx-build`, so the module docs would never get generated.
MarkusH added a commit to crate/crate-operator that referenced this issue Sep 30, 2020
This change has the benefit of supporting ReadTheDocs builds as
discussed in readthedocs/readthedocs.org#1139
MarkusH added a commit to crate/crate-operator that referenced this issue Sep 30, 2020
This change has the benefit of supporting ReadTheDocs builds as
discussed in readthedocs/readthedocs.org#1139
MarkusH added a commit to crate/crate-operator that referenced this issue Oct 2, 2020
This change has the benefit of supporting ReadTheDocs builds as
discussed in readthedocs/readthedocs.org#1139
MarkusH added a commit to crate/crate-operator that referenced this issue Oct 2, 2020
This change has the benefit of supporting ReadTheDocs builds as
discussed in readthedocs/readthedocs.org#1139
@SBCV
Copy link

SBCV commented Oct 23, 2020

With Sphinx 3.1.1 I needed to import
from sphinx.ext.apidoc import main
instead of
from sphinx.apidoc import main

SteVwonder added a commit to SteVwonder/psi-j-python that referenced this issue May 18, 2021
Problem: when the documentation is built by ReadTheDocs with Sphinx,
they (RTD) do not run autodoc first, resulting in a mostly empty doc
site.

Solution: follow the workaround prescribed in
readthedocs/readthedocs.org#1139 and add code
to the conf.py to run autodoc as part of the normal sphinx build process
kevinanewman added a commit to USEPA/EPA_OMEGA_Model that referenced this issue Jun 24, 2021
yoda-vid added a commit to sanderslab/magellanmapper that referenced this issue Mar 22, 2022
Build the `.rst` files required to generate the API docs in ReadTheDocs. Although these files can be generated through a CLI flag, they are not built automatically during RTD generation. As inspired by this comment (readthedocs/readthedocs.org#1139 (comment)), add configuration steps to build the files automatically. This build avoids the need to commit the RST files to the repo.
yoda-vid added a commit to sanderslab/magellanmapper that referenced this issue Mar 22, 2022
Build the `.rst` files required to generate the API docs in ReadTheDocs. Although these files can be generated through a CLI flag, they are not built automatically during RTD generation. As inspired by this comment (readthedocs/readthedocs.org#1139 (comment)), add configuration steps to build the files automatically. This build avoids the need to commit the RST files to the repo.
kevinoid added a commit to kevinoid/python-project-template that referenced this issue Jun 18, 2022
To build API documentation as part of sphinx-build, rather than
requiring a prior separate invocation of sphinx-apidoc (which requires
additional knowledge/configuration, e.g. on Read the Docs).  See:
readthedocs/readthedocs.org#1139
sphinx-doc/sphinx#4101

Signed-off-by: Kevin Locke <kevin@kevinlocke.name>
kevinoid added a commit to kevinoid/python-project-template that referenced this issue Jun 18, 2022
To build API documentation as part of sphinx-build, rather than
requiring a prior separate invocation of sphinx-apidoc (which requires
additional knowledge/configuration, e.g. on Read the Docs).  See:
readthedocs/readthedocs.org#1139
sphinx-doc/sphinx#4101

Signed-off-by: Kevin Locke <kevin@kevinlocke.name>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Needed: documentation Documentation is required Needed: more information A reply from issue author is required
Projects
None yet
Development

No branches or pull requests