README for lore2sphinx

A tool for converting Twisted Lore format documentation into Sphinx/ReST format.

Distribution currently includes the lore2sphinx tool as well as a sphinx project (for the Twisted docs) with a few hand-edited files that tie the docs for the various parts of Twisted together.

NOTE: Output generated from this tool (for the Twisted project) should go
in the "projects" subdirectory of the sphinx project! This directory is not under version control, you will have to create it yourself.


This tool requires:

  • Python 2.6+
  • lxml
  • copy of Twisted

Using the tool

  1. Get it:

    hg clone http://bitbucket.org/khorn/lore2sphinx

  2. Install with 'python setup.py install'

  3. Copy 'lore2sphinx.conf.default' to 'lore2sphinx.conf'

  4. Edit 'lore2sphinx.conf' to point to your Lore input source and rst output directories

  5. Run bin/lore2sphinx. This will generate the rst files for Sphinx.
    • If the script can't find your lore2sphinx.conf file, use the '-c' option to specify the config file's exact location. Specify the '--help' command to see all available options.
  6. Build the Sphinx project:

    cd profiles/twisted make html

  7. Look at the output in build/html/ to see what's broken

  8. Give feedback! Open a ticket on Bitbucket or use the Twisted-Python mailinglist.