goerz / better-apidoc Goto Github PK
View Code? Open in Web Editor NEWA version of sphinx-apidoc with support for templating
License: BSD 2-Clause "Simplified" License
A version of sphinx-apidoc with support for templating
License: BSD 2-Clause "Simplified" License
The version of better-apidoc on PyPI is v1.2, and doesn't include the latest changes for forward compatibility with Sphinx 1.7. Any chance of a new release?
Hey,
thank you for the useful template integration to apidoc! Unfortunately, it appears to be out of sync with sphinx since their recent update to v1.7:
https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/apidoc.py
In particular, the following line gives an import error now:
better-apidoc/better_apidoc.py
Line 35 in b52b365
since it changed to from sphinx.cmd.quickstart import EXTENSIONS
.
Thanks a lot for an update!
When I try to run command:
>> better-apidoc --templates=templatedir -o outputdir ..
error: option --templates not recognized
Otherwise this works but when using the --templates or -t option flags and there is a setup.py in source directory then this will fail. Error message is always that some option parameter is not recognized. This is because importlib.import_module('setup')
doesn't work.
You can circumvent this problem by adding setup.py into your exclude list.
Ubuntu
Python 2.7.12
Hi,
I was running into the following error
Running Sphinx v4.0.0
making output directory... done
[autosummary] generating autosummary for: XXX
Extension error:
Handler <function run_apidoc at 0x7f83a4aa1550> for event 'builder-inited' threw an exception (exception: cannot import name 'walk' from 'sphinx.util.osutil' (XXX/lib/python3.8/site-packages/sphinx/util/osutil.py))
make: *** [html] Error 2
Turns out the problem comes from import better_apidoc
in conf.py
. The fix is extremely simple: just don't use the walk
from sphinx, but use os.walk
.
https://github.com/goerz/better-apidoc/blob/master/better_apidoc.py#L39
As it turns out, sphinx.utils.walk
is deprecated anyway. See https://www.sphinx-doc.org/en/master/changes.html#id96.
Do you guys think it is a good idea to fix this?
VERSION: better-apidoc 0.1.4
Whenever I run:
better-apidoc -t ./_templates -f ../song_match -o song_match
I get the following error:
WARNING: failed to import 'song_match': No module named 'song_match'
Traceback (most recent call last):
File "/home/g/anaconda3/bin/better-apidoc", line 11, in <module>
sys.exit(main())
File "/home/g/anaconda3/lib/python3.6/site-packages/better_apidoc.py", line 604, in main
modules = recurse_tree(rootpath, excludes, opts)
File "/home/g/anaconda3/lib/python3.6/site-packages/better_apidoc.py", line 462, in recurse_tree
py_files, opts, subs, is_namespace)
File "/home/g/anaconda3/lib/python3.6/site-packages/better_apidoc.py", line 365, in create_package_file
text = template.render(**package_ns)
UnboundLocalError: local variable 'package_ns' referenced before assignment
Not sure what I'm doing wrong.
I run the command within ./docs
. Here's a snippet of my package structure.
.
├── docs
│ └── _templates
│ ├── module.rst
│ └── package.rst
├── song_match
│ ├── config.py
... The rest is omitted
Whenever I try sphinx-apidoc -f ../song_match -o song_match
it works fine.
Any help?
Now getting:
Exception occurred:
documenter = get_documenter(app=APP, obj=member, parent=mod)
TypeError: get_documenter() got an unexpected keyword argument 'app'
The sub package filter in the create_package_file
function also removes implicit namespace packages (i.e.,
better-apidoc/better_apidoc.py
Line 453 in e1e4c59
The issue is apparently already fixed in the upstream apidoc tool which performs the filtering using shall_skip
(see https://github.com/sphinx-doc/sphinx/blob/b135e7ce4a919f73c04e376a14ce597b0f160cac/sphinx/ext/apidoc.py#L128-L129). Could you adopt this change into better-apidoc?
Furthermore, given that other changes like, for example, exclude support for shall_skip
have been added upstream, I wonder if you plan to rebase better-apidoc on a more recent version of sphinx-apidoc in general.
In the readme it says:
This release breaks templates written for v1.0.x
But surely you meant
v0.1.x
It is not really a serious issue, just thought I mention it.
I can run this without issue:
sphinx-apidoc -f --implicit-namespaces --no-toc --ext-todo --ext-intersphinx --ext-viewcode -o source/apidoc <excludes>
without issue
However when I run the same with better-apidoc like this:
better-apidoc -t './rst_template_dir' -f --implicit-namespaces --no-toc --ext-todo --ext-intersphinx --ext-viewcode -o source/apidoc <excludes>
I get the following:
Traceback (most recent call last):
File "c:\anaconda3\envs\py352\lib\runpy.py", line 184, in _run_module_as_main
"__main__", mod_spec)
File "c:\anaconda3\envs\py352\lib\runpy.py", line 85, in _run_code
exec(code, run_globals)
File "C:\Anaconda3\envs\py352\Scripts\better-apidoc.exe\__main__.py", line 9, in <module>
File "c:\anaconda3\envs\py352\lib\site-packages\better_apidoc.py", line 600, in main
modules = recurse_tree(rootpath, excludes, opts)
File "c:\anaconda3\envs\py352\lib\site-packages\better_apidoc.py", line 458, in recurse_tree
py_files, opts, subs, is_namespace)
File "c:\anaconda3\envs\py352\lib\site-packages\better_apidoc.py", line 318, in create_package_file
includeprivate=opts.includeprivate)
File "c:\anaconda3\envs\py352\lib\site-packages\better_apidoc.py", line 270, in _get_mod_ns
mod = importlib.import_module(fullname)
File "c:\anaconda3\envs\py352\lib\importlib\__init__.py", line 126, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
File "<frozen importlib._bootstrap>", line 981, in _gcd_import
File "<frozen importlib._bootstrap>", line 933, in _sanity_check
ValueError: Empty module name
make: *** [rst] Error 1
> pip show better-apidoc
Name: better-apidoc
Version: 0.1.2
I don't appear to get any error when not using --implicit-namespaces: for whatever that's worth.
I really like your work. Will you continue to work towards incorporating it back to sphinx-apidoc?
Getting the following error now that I've installed Sphinx 1.8:
Traceback (most recent call last):
File "/home/jsivak/personal/knowledge_ve/bin/better-apidoc", line 6, in <module>
from better_apidoc import main
File "/home/jsivak/personal/knowledge_ve/lib/python3.7/site-packages/better_apidoc.py", line 51, in <module>
from sphinx.ext.autodoc import add_documenter, \
ImportError: cannot import name 'add_documenter' from 'sphinx.ext.autodoc' (/home/jsivak/personal/knowledge_ve/lib/python3.7/site-packages/sphinx/ext/autodoc/__init__.py)
The Sphinx 1.7 change log indicates that the "add_documenter()" function was going to be removed, and now in 1.8 it is actually removed.
I've forked the repo, but I don't know how to get an "app" object so that I can update the code to use "Please use app.add_autodocumenter() instead." as specified in the change log.
Any ideas/pointers?
Thanks
I think that including a reasonable example of package.rst and module.rst would be of huge help for everyone who'd like to use this package. Many of the people who come here, do because they'd like to strip away the "Submodules/Subpackages" headers and the "module/package" suffixes. A template that does that would be a good start.
This package depends on six and docutils but they are not in requirements. Running it with updated docs dependencies on Python 3.8 I got:
Extension error:
Handler <function run_apidoc at 0x000001E245CEF160> for event 'builder-inited' threw an exception
(exception: No module named 'six')
Adding six to my docs requirements solved the problem of course. But this should not be necessary.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.