Bad docs/conf.py breaks Sphinx

[jwmullally]

"sphinx-build" can fail due to broken code paths in docs/conf.py (and possible elsewhere) which normally are never exercised during standard "pip install" and hence unnoticed by upstream.

Ideally these would be fixed upstream, but because the PyPI package is otherwise fine and the author is not always testing the docs, it could mean recurring unnecessary hardship for pyp2rpm users.

Possible solutions:

• Disable Sphinx by default (maybe have a 2 templates, default and "-full")
• Make "sphinx-build" failures non-fatal but no-op
• Make it non-fatal with a fallback conf.py

Also, I don't have any good examples on hand right now, but I suspect Sphinx's usage of "autodoc" requires all modules to be imported, which would practically mean all dependencies would need to be added to the rpm BuildRequires to be available at build time. I don't know if that's a good idea or not, seems like a bad default. Again an ImportError exception handler could catch this case and fallback to some kind of parse-only documentation.

Examples

(tested under fc25 with pyp2rpm 3.2.1)

Broken docs/conf.py: Files referenced are not included in the pypi package

In this case "docs/_themes" is referenced here: https://github.com/sublee/flask-autoindex/blob/1e086477c6881c9e40d77359f8a33e47da02b454/docs/conf.py#L21 is included in the upstream gitrepo (through submodule) https://github.com/sublee/flask-autoindex/tree/1e086477c6881c9e40d77359f8a33e47da02b454/docs but not included in the pypi package:

$ pyp2rpm --srpm Flask-AutoIndex
$ mock ~/rpmbuild/SRPMS/python-Flask-AutoIndex-0.6-1.fc25.src.rpm
...
+ sphinx-build docs html
...
Theme error:
no theme named 'flask_small' found (missing theme.conf?)

$ pip download --no-deps Flask-AutoIndex
$ tar -ztf Flask-AutoIndex-0.6.tar.gz  | grep "/docs/_themes"
### docs/_themes is missing...

---

Broken docs/conf.py: tries to load non-existant module with different case

https://github.com/hgrecco/pyvisa/blob/ceb97d09a45f786311e933691ade1660938bb386/docs/conf.py#L51

$ pyp2rpm --srpm PyVISA
$ mock ~/rpmbuild/SRPMS/python-PyVISA-1.8-1.fc25.src.rpm
...
+ sphinx-build docs html
...
DistributionNotFound: The 'PyVISA' distribution was not found and is required by the application

[mcyprian]

Thank you for well structured description of the problem, I will definitely try to improve pyp2rpm's performance on packages containing sphinx documentation.