Issue #1073 on hold

Problems building documentation (example with Zope)

Anonymous created an issue


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

If I understood the are imported from the 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

  2. cd /tmp

  3. svn co svn:// 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/", 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, or report them in the tracker at 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
    $ python --no-site-packages pyenv
    $ . pyenv/bin/activate
    (pyenv)$ pip install sphinx
    (pyenv)$ svn co svn:// 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.

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

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

    The flask documentation is a good example.

    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