goerz / better-apidoc Goto Github PK

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:

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.,

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.