I'm using Sphinx in order to autodocument a flask api. Everything seems to work pretty well, but I have a really weird problem. The problem can be bypassed, but the bypass isn't ideal.
When I run make html Sphinx runs through
(env)vagrant@dweloDevEnv:~/make html
sphinx-build -E -a -b html -d _build/doctrees . _build/html
Running Sphinx v1.3.1
building [mo]: all of 0 po files
building [html]: all source files
updating environment: 1 added, 0 changed, 0 removed
* Running on http://127.0.0.1:9001/
* Restarting with reloader
Running Sphinx v1.3.1
building [mo]: all of 0 po files
building [html]: all source files
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
At the above line, sphinx hangs. I have left it for a full minute, but it won't continue. If I kill the process with cntrl + c, the process actually completes seemingly successfully:
reading sources... [100%] index
^C
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents...
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
doneing output... [100%] index
writing output... [100%] index
generating indices... genindex
generating indices... genindex http-routingtable http-routingtable
writing additional pages... search
writing additional pages... search
copying static files...
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
copying extra files... done
dumping search index in English (code: en) ... done
build succeeded.
done
dumping object inventory... done
build succeeded.
If I go check the output directories, I do indeed find the documentation for my api. Great! Unfortunately, this approach makes it impossible for me to embed the process in a shell script (because I have to kill the process to get passed the hang). My rst file is very simple. I've included it below:
my_app.rst
Contents:
.. toctree::
:maxdepth: 2
.. autoflask:: my_api.run:api.app
:undoc-static:
:blueprints: v1_api
:include-empty-docstring:
I've been banging away for a very long time and can't seem to figure out what is going wrong. The lack of any useful error messages doesn't make it any easier. Has anyone encountered this in the past?
The problem ended up being that I was actually executing the api (app.run) in the my_app.py file. So, while the app object was available and ended up getting interpreted, I was hanging up because the api was being brought online.