"add_documenter()" is now removed from Sphinx 1.8

[jsivak]

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

[goerz]

You're right. Unfortunately, I don't think it's possible to really fix this: the app object is available in conf.py (and, from there, is passed to any Sphinx extensions). I don't see any way to get an app object cleanly into better-apidoc, as a script.

I just pushed a very ugly workaround: have a global variable APP in the sphinx-apidoc script, and set that variable from conf.py before calling sphinx-apidoc.main(). This is not a permanent solution. The changes in Sphinx 1.7/1.8 make sphinx-apidoc in its current form impossible. I see only one option: refactor the script into a Sphinx extension, not a standalone script. I actually think this a good idea in any case. It will greatly simplify how apidoc is incorporated into the build process. I never liked that the original apidoc was designed as a script that has to be run manually/via a modified Makefile before sphinx itself generates the documentation. Indeed, I was already invoking better-apidoc from inside conf.py, so that I didn't have to touch docs/Makefile. It would certainly be much cleaner to just add an apidoc to the list of extensions in conf.py, and set options like the location of the API files to be generated and the templates to be used as variables, also in conf.py.

Refactoring into an extensions is not a crazily complicated change, but at the moment I cannot give any estimate on when I might have time to do this. For the moment, "it works for me", which I realize is not very satisfactory to anyone else using the script. For the time being, you'll have to use the same ugly workarounds I'm using.

[goerz]

Refactoring into an extension would also solve #2, #3, #9, #11

[jsivak]

Gotcha, thanks for the explanation and "hacks" to potentially keep better-apidoc somewhat working for the time being.

[goerz]

The plan is to merge into the sphinxcontrib.apidoc extension in the relatively near future.

[goerz]

Update: apidoc recently added basic templating, and I've opened a pull request to merge better-apidoc back into apidoc: sphinx-doc/sphinx#6768