-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
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
Comments
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 |
I'm also trying to use sphinx-apidoc for my documentation. I use a |
+1 on this... I'm sure, even documenting it in the release procedure, that I'll forget to generate the apidocs and commit them... |
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. |
+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. |
+1 |
2 similar comments
👍 |
+1 |
+1 |
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. |
Another solution which doesn't involve directly calling a subprocess is to use the following in conf.py:
instead of
This solved one of the issues I had was with long path names which are restricted on readthedocs. |
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
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...
@alyjak @Maxyme Thanks. And this works for me.
|
Thank you! For your code to work, however, you would need to uncomment the 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) |
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.
This change has the benefit of supporting ReadTheDocs builds as discussed in readthedocs/readthedocs.org#1139
This change has the benefit of supporting ReadTheDocs builds as discussed in readthedocs/readthedocs.org#1139
This change has the benefit of supporting ReadTheDocs builds as discussed in readthedocs/readthedocs.org#1139
This change has the benefit of supporting ReadTheDocs builds as discussed in readthedocs/readthedocs.org#1139
With |
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
…he .rst files itself see readthedocs/readthedocs.org#1139
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.
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.
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>
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>
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.The text was updated successfully, but these errors were encountered: