Description
If we want to remove the autogenerated files containing commands/config docs
from the repository, we need to make their generation work on readthedocs.
At the moment, the files in docs/source/usage/ as well as docs/source/configuration/*table*
are generated by docs/source/generate_commands.py and docs/source/generate_configs.py,
which get called by make.
RTD do not use make but instead call sphinx directly. The build goes through without those generated files but is obviously missing their content then.
One way to get fix this is to generate those files from within docs/source/conf.py.
The problem is that these scripts import alot in order to extract the docstrings,
and that some required modules are mocked out when running sphinx on RTD.
I added a branch https://github.com/pazz/alot/tree/doctest where i tried all this.
It currently does not build properly on RTD: https://readthedocs.org/projects/alot/builds/4888879/
The log is below.
Running Sphinx v1.3.5
making output directory...
Traceback (most recent call last):
File "/home/docs/checkouts/readthedocs.org/user_builds/alot/envs/doctest/local/lib/python2.7/site-packages/sphinx/cmdline.py", line 243, in main
opts.warningiserror, opts.tags, opts.verbosity, opts.jobs)
File "/home/docs/checkouts/readthedocs.org/user_builds/alot/envs/doctest/local/lib/python2.7/site-packages/sphinx/application.py", line 127, in __init__
confoverrides or {}, self.tags)
File "/home/docs/checkouts/readthedocs.org/user_builds/alot/envs/doctest/local/lib/python2.7/site-packages/sphinx/config.py", line 277, in __init__
execfile_(filename, config)
File "/home/docs/checkouts/readthedocs.org/user_builds/alot/envs/doctest/local/lib/python2.7/site-packages/sphinx/util/pycompat.py", line 128, in execfile_
exec_(code, _globals)
File "/home/docs/checkouts/readthedocs.org/user_builds/alot/envs/doctest/local/lib/python2.7/site-packages/six.py", line 699, in exec_
exec("""exec _code_ in _globs_, _locs_""")
File "<string>", line 1, in <module>
File "conf.py", line 10, in <module>
from .generate_commands import generate_command_tables
File "/home/docs/checkouts/readthedocs.org/user_builds/alot/checkouts/doctest/docs/source/generate_commands.py", line 5, in <module>
from alot.commands import *
File "/home/docs/checkouts/readthedocs.org/user_builds/alot/checkouts/doctest/docs/source/../../alot/commands/__init__.py", line 10, in <module>
from ..settings import settings
File "/home/docs/checkouts/readthedocs.org/user_builds/alot/checkouts/doctest/docs/source/../../alot/settings/__init__.py", line 4, in <module>
from .manager import SettingsManager
File "/home/docs/checkouts/readthedocs.org/user_builds/alot/checkouts/doctest/docs/source/../../alot/settings/manager.py", line 9, in <module>
from configobj import ConfigObj, Section
ImportError: No module named configobj
Exception occurred:
File "/home/docs/checkouts/readthedocs.org/user_builds/alot/checkouts/doctest/docs/source/../../alot/settings/manager.py", line 9, in <module>
from configobj import ConfigObj, Section
ImportError: No module named configobj
The full traceback has been saved in /tmp/sphinx-err-njHBX0.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!