[cctbxbb] building sphinx documentation

Fri Apr 19 14:09:54 PDT 2013

With Nat's help I have managed to get it working by modifying build_docs.sh
by replacing LD_LIBRARY_PATH with DYLD_LIBRARY_PATH (needed for mac os x),
and added the line export LIBTBX_BUILD=/path/to/cctbx/build/. Is there a
way to tell sphinx-build to use the cctbx.python without editing the
sphinx-build file?

A couple of comments based on a successful run of documentation build:

1) It seems that sphinx tries to import absolutely every import command it
finds in the files - in the cctbx there are a lot of conditional imports
that depend on certain external packages being present. Therefore it seems
that unless I have absolutely every package installed and build every
module, then I will end up with a huge number of tracebacks in the output
from sphinx. I am not sure if there is anything that can be done about this.

2) Is there a way to tell sphinx not to look at certain files? I don't
claim to understand how the libtbx_refresh.py modules work, but sphinx
tries to import them, and unsurprisingly fails.

Cheers,

Richard

On 19 April 2013 13:37, James Stroud <xtald00d at gmail.com> wrote:

> On Apr 19, 2013, at 2:09 PM, Richard Gildea wrote:
>
> Hi Jan,
>
> I think the cause of the incomplete documentation is down to the fact that
> when I run build_docs.sh I get a whole bunch of import errors for every
> compiled module that it tries to import. I am at a bit of a loss as to why
> this should be the case, as running the tests or importing modules at the
> command line works just fine. I have built cctbx using the system python
> (2.7.2) on mac os x (mountain lion).
>
>
> It looks like sphinx-build is not using cctbx.python, so it has no idea
> from where to import the python modules. Try this
>
> % your-favorite-editor `which sphinx-build`
>
>
> And change the first line to something like
>
> #! /path/to/cctbx.python
>
>
> That line shouldn't point to the python that cctbx.python calls (i.e. the
> system python).
>
> This assumes you did the following when you installed sphinx:
>
> /path/to/cctbx.python setup.py build
> /path/to/cctbx.python setup.py install
>
>
> (or at least used the python called by cctbx.python in these two steps).
>
> James
>
>
>
> Install sphinx:
>
> http://sphinx-doc.org/latest/install.html#mac-os-x-install-sphinx-using-macports
>   sudo port install py27-sphinx
>   sudo port select --set python python27
>
> This is the output I get on running ./build_docs.sh:
>
> sphinx-build -b coverage -d _build/doctrees -D latex_paper_size=a4  .
> _build/coverage
> Running Sphinx v1.1.3
> loading pickled environment... not yet created
> building [coverage]: coverage overview
> updating environment: 129 added, 0 changed, 0 removed
> Traceback (most recent call last):
>
>
>   File
> "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/sphinx/ext/autodoc.py",
> line 321, in import_object
>     __import__(self.modname)
>   File "/Users/rjgildea/cctbx/sources/cctbx_project/cctbx/adptbx.py", line
> 2, in <module>
>     from cctbx.array_family import flex # for tuple mappings
>   File
> "/Users/rjgildea/cctbx/sources/cctbx_project/cctbx/array_family/flex.py",
> line 2, in <module>
>     import scitbx.array_family.flex
>   File
> "/Users/rjgildea/cctbx/sources/cctbx_project/scitbx/array_family/flex.py",
> line 2, in <module>
>     import boost.optional # import dependency
>   File
> "/Users/rjgildea/cctbx/sources/cctbx_project/boost_adaptbx/boost/optional.py",
> line 2, in <module>
>     import boost.python
>   File
> "/Users/rjgildea/cctbx/sources/cctbx_project/boost_adaptbx/boost/python.py",
> line 57, in <module>
>     ext = import_ext("boost_python_meta_ext")
>   File
> "/Users/rjgildea/cctbx/sources/cctbx_project/boost_adaptbx/boost/python.py",
> line 36, in import_ext
>     + ["  "+p for p in sys.path]))
> ImportError: __import__("boost_python_meta_ext"):
> dlopen(/Users/rjgildea/cctbx/system_python_build/lib/boost_python_meta_ext.so,
> 2): Library not loaded: lib/libboost_python.dylib
>   Referenced from:
> /Users/rjgildea/cctbx/system_python_build/lib/boost_python_meta_ext.so
>   Reason: image not found
>   sys.path:
>     /Users/rjgildea/cctbx/sources/cctbx_project
>     /Users/rjgildea/cctbx/sources
>     /Users/rjgildea/cctbx/sources/cctbx_project/clipper_adaptbx
>     /Users/rjgildea/cctbx/sources/cctbx_project/boost_adaptbx
>     /Users/rjgildea/cctbx/sources/cctbx_project/libtbx/pythonpath
>     /Users/rjgildea/cctbx/system_python_build/lib
>     /Users/rjgildea/cctbx/system_python_build/bin
>     /opt/local/Library/Frameworks/Python.framework/Versions/2.7/bin
>     /Library/Python/2.7/site-packages/docutils-0.10-py2.7.egg
>     /Library/Python/2.7/site-packages/Jinja2-2.6-py2.7.egg
>     /Library/Python/2.7/site-packages/Pygments-1.6-py2.7.egg
>
> /opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python27.zip
>
> /opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7
>
> /opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/plat-darwin
>
> /opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/plat-mac
>
> /opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/plat-mac/lib-scriptpackages
>
> /opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-tk
>
> /opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-old
>
> /opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-dynload
>
> /opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages
>
> /opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/setuptools-0.6c11-py2.7.egg-info
>     /Library/Python/2.7/site-packages
>
> etc.
>
> Do you have any idea what I am might be doing wrong here?
>
> Cheers,
>
> Richard
>
>
> On 19 April 2013 05:10, Jan Marten Simons <marten at xtal.rwth-aachen.de>wrote:
>
>> Am Donnerstag 18 April 2013 19:16:00 schrieben Sie:
>> > Hi Jan,
>>
>> Hi Richard,
>>
>> > I have attempted to build the sphinx documentation using
>> > dox.sphinx/build_docs.sh, and this appears to have run successfully and
>> > produced some html which shows the table of contents etc. However, I
>> can't
>> > seem to find the documentation for any of the significant modules, e.g.
>> > cctbx/xray/structure.py. When I navigate to the link for the structure
>> > module within the xray package
>> > (dox.sphinx/_build/html/cctbx/cctbx.xray.html#structure-module), I see
>> > nothing other than a list of all the modules within the xray package.
>> Am I
>> > missing something here?
>>
>> Have you followed the instructions given in the comments at the top of
>> dox.sphinx/build_docs.sh?
>>
>> Which version of Sphinx do you use? I'm using 1.1.3 regularly and get
>> useful
>> documentation (I've attached the "makescript" I use to build cctbx and the
>> sphinx documentation. If you are interested in it I can also put the
>> output of
>> the sphinx run on my system with current svn on webserver over here.). Has
>> your sphinx build completed successfully or did it abort (e.g. due to out
>> of
>> memory* or due to other problems)?
>> Could you also check if build/dox.sphinx/cctbx/cctbx.xray.rst has all
>> modules
>> listed?
>>
>> > As a novice to using sphinx, I don't like to add significant
>> documentation
>> > in sphinx style without being able to check via generating the
>> > documentation that what I have written is correct sphinx-speak.
>> I can totally understand this ;).
>>
>> Cheers and hopefully we can get this working for you as well,
>> Jan
>>
>> *) For me running sphinx with all those modules selected needs about 3.3
>> GiB
>> of virtual memory (RAM) and takes a few minutes to actually finish.
>>
>> p.s.: Sorry didn't hit "reply all".
>>
>> _______________________________________________
>> cctbxbb mailing list
>> cctbxbb at phenix-online.org
>> http://phenix-online.org/mailman/listinfo/cctbxbb
>>
>>
> _______________________________________________
> cctbxbb mailing list
> cctbxbb at phenix-online.org
> http://phenix-online.org/mailman/listinfo/cctbxbb
>
>
>
> _______________________________________________
> cctbxbb mailing list
> cctbxbb at phenix-online.org
> http://phenix-online.org/mailman/listinfo/cctbxbb
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://phenix-online.org/pipermail/cctbxbb/attachments/20130419/28e62b4c/attachment.htm>