Cannot build sphinx documentation for Brian2
DylanMuir opened this issue · comments
I am trying to build the Sphinx documentation for Brian2. I have doc2dash 2.2.0 installed on python 2.7 using conda (package from conda_forge).
doc2dash -n Brian-2.1.2 -A -f --parser doc2dash.parsers.intersphinx.InterSphinxParser docs_sphinx results in a long list of "filename too long" errors:
File "/Users/dylan/anaconda/envs/py27/lib/python2.7/shutil.py", line 208, in copytree
raise Error, errors
shutil.Error: [('/Users/dylan/Development/brian2_dev_GIT/docs_sphinx/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/.gitignore', u'/Users/dylan/Library/Application Support/doc2dash/DocSets/Brian-2.1.2.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/.gitignore', "[Errno 63] File name too long: u'/Users/dylan/Library/Application Support/doc2dash/DocSets/Brian-2.1.2.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/docs_sphinx.docset/Contents/Resources/Documents/.gitignore'"), ...
and then fails.
The command doc2dash -n Brian-2.1.2 -A -f docs_sphinx results in the error
"/Users/dylan/Development/brian2_dev_GIT/docs_sphinx" does not contain a known documentation format.
The document set builds successfully using sphinx. Please let me know where I should start looking to fix this problem.
You need to run doc2dash on built docs, not their sources. With some work, I was able to build their docs by installing the package and sphinx (pip install -e . sphinx) into a virtualenv and then running sphinx-build -b html -d _build/doctrees . _build/html and doc2dash _build/html/ -n brian2 inside of docs_sphinx.
Thanks for your help. I could get a nice docset built using the command doc2dash _build/html/ -n Brian2 -I index.html.
It wasn't clear to me from the doc2dash documentation that I needed to run doc2dash on the built docs and not on the sources.