[Twisted-Python] Lore to Sphinx Conversion Progress Report 4

[Kevin Horn]

This time I think I'm gonna skip saying how I haven't gotten as much done as
I would like...oh darn.

Anyways, time for another gripping installment...

Progress:
  - tables are now handled (mostly) properly, thanks to Zeth at
http://commandline.org.uk/
  - blockquote tags handled
  - much improved whitespace/indentation handling
  - some nicer styling thanks to Michael Thompson
  - I've managed to convert the docs for the 3 Divmod projects with Lore
    docs, though I've yet to put them up anywhere.


Oustanding issues:
  - two files in the Lore source are not yet being converted, but it looks
like
    one of them is about to be removed
    (http://twistedmatrix.com/trac/ticket/4188), and it's not really a
    Lore doc anyways.
  - due to ReST's insistence on "inline markup" being surrounded by
    whitespace or certain special characters, there are a lot of places
where
    such inline markup gets jacked up, by not including whitespace in front
of
    it.  If I put whitespace in front of everything though, my indentation
    handling gets jacked up and about 400+ Sphinx build warning result.
    Not sure if I should spend the time to make whitespace handling really
    smart or if these should just be fixed manually post-conversion.
  - cite tags still need handling...not hard, just haven't decided the best
    way to do it yet.
  - Themeing/styling: still mostly a TODO, though new styling looks a lot
    better than the default to my eyes.  I'm starting to think that
    eventually we might want to have 2 themes/styles...one to match the
    trac-based website, and one for bundled docs (docs tarballs, CHM files,
etc.)
  - auto-generated toctree directives are currently generated in
alphabetical
    order, which makes the "prev" and "next" links mostly make no sense
  - some of the Lore source files have nested "inline markup", which ReST
    disallows.  This can be handled by:
      - fix the markup in the Lore source
      - figure out some kind of supersmart auto-conversion for every
possible
        combination of nesting
      - just handle the outside level of nesting (what I'm doing now) and
        fix any problems manually post-conversion.
  - xhtml entities are not currently resolved...mostly because it makes
    the build take a LOOOONG time.  They can be though.  This shouldn't
    be a problem.
  - xhtml comments still need to be handled
  - <code class="API"> tags need something better..right now they are just
    the same as <code> tags...Sphinx has an upcoming feature coming in 1.0
    that would make this nice and maintainable in the long run, but I don't
    know that I want to wait for it.  I may try to "backport" the extension
    or just come up with a separate solution.
  - some of the generated links need fixing
    (e.g. links to directories, .py files)

In other news:

  - Foolscap 0.5 was released today, which made me wonder what they use for
    docs...and it's Lore.  I brought this up on IRC, and it was suggested
    by many that Lore should stick around even after the conversion
according
    to the standard Twisted compatibility policy, to give anyone who still
    uses it time to migrate.  This sounds like a fine idea to me.
    Any thoughts?


As always, the lore2sphinx code is here:
http://bitbucket.org/khorn/lore2sphinx/

And the sample output of the conversion process is here:
http://twistedsphinx.funsize.net/

Cheers,

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20100119/811174b1/attachment.html>