Issues

Issue #1073 on hold

Problems building documentation (example with Zope)

Anonymous created an issue

Hello,

recently I began trying to customize the look of documentation Sphinx generates. Reading documentation was not of much use for it.

I went on to finding examples in some open source projects. This has been particularly frustrasting because the look of the generated HTML pages or PDF files I see is not on the source files themselves, and are neither in the conf.py.

If I understood the are imported from the conf.py files. But how to locate these files? Can the reside in the documentation directory, so documentation can compile with all files only in its dir?

Compiling the documentation has been a challenge for me in some projects. And I feel I'm far from my primary objective: understand how to customize some of the look of the generated docs, mainly in latex and html outputs.

I don't know Python, and this also seem to have added to my difficulty.

The example I choose to show my problem is Zope documentation. They have made some guide to compile the documentation, but it didn't work me:

  1. Building the HTML Documentation for Zope (from http://docs.zope.org/developer/sphinx-documentation.html)

  2. cd /tmp

  3. svn co svn://svn.zope.org/repos/main/zope.event/trunk event-trunk

  4. cd event-trunk/docs

  5. make html

In the last step I have this in my terminal:


$ make html sphinx-build -b html -d _build/doctrees . _build/html Making output directory... Running Sphinx v1.0.1

Exception occurred: File "/usr/lib/python2.7/dist-packages/pkg_resources.py", line 552, in resolve raise DistributionNotFound(req) DistributionNotFound: zope.event The full traceback has been saved in /tmp/sphinx-err-D4GnFh.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. Either send bugs to the mailing list at http://groups.google.com/group/sphinx-dev/, or report them in the tracker at http://bitbucket.org/birkenfeld/sphinx/issues/. Thanks! make: ** [html] Erro 1


Comments (5)

  1. Jon Waltman

    The example I choose to show my problem is Zope documentation. They have made some guide to compile the documentation, but it didn't work me:

    The problem here is that the documentation is being automatically generated by importing and introspecting live Python objects from the zope.event package. You need to have that package installed on your system before building the docs.

    Python packaging and distribution is a bit of a mess really, but here we go:

    $ curl -O https://raw.github.com/pypa/virtualenv/master/virtualenv.py
    $ python virtualenv.py --no-site-packages pyenv
    $ . pyenv/bin/activate
    (pyenv)$ pip install sphinx
    (pyenv)$ svn co svn://svn.zope.org/repos/main/zope.event/trunk event-trunk
    (pyenv)$ pip install -e event-trunk
    (pyenv)$ cd event-trunk/docs
    (pyenv)$ make html
    

    Refer to the pip and virtualenv documentation for info on installing Python packages.

    Customizing the html can be done by using one of the different html_themes included with Sphinx.

    http://sphinx-doc.org/theming.html

    More advanced customization is going to require writing your own templates.

    http://sphinx-doc.org/templating.html

    Customizing the PDFs is going to require extensive knowledge of LaTeX and the internal workings of Sphinx. :-)

    The flask documentation is a good example.

    http://flask.pocoo.org/docs/

    It is admittedly rather complex to customize the output of Sphinx but it does enable you to make significant changes if you know how to use it.

    Good luck!

  2. Log in to comment