Content Skeleton

This Page

Previous topic

Migration from Trac/SVN

Next topic


Conversion of Trac wiki to Sphinx rst



Trac Formatter based

Checkout the trac source

trac- tractrac- tractrac-cd

Formatters such as Trac2MediaWiki work by extending the with a large-ish number of specialization formatter methods. Crucial part of subclasses, are the internal handlers with method signature convention _<type>_formatter(match, fullmatch). The formatter methods as invoked by the handle_match method.

# -- Wiki engine

 def handle_match(self, fullmatch):
     for itype, match in fullmatch.groupdict().items():
         if match and not itype in self.wikiparser.helper_patterns:
             # Check for preceding escape character '!'
             if match[0] == '!':
                 return escape(match[1:])
             if itype in self.wikiparser.external_handlers:
                 external_handler = self.wikiparser.external_handlers[itype]
                 return external_handler(self, match, fullmatch)
                 internal_handler = getattr(self, '_%s_formatter' % itype)
                 return internal_handler(match, fullmatch)

The formatter is plugged into trac component system via:

class Trac2MediaWikiPlugin(Component):

Metadata preservation

Need to find Sphinx/RST equivalent representation of Trac metadata, and preserve this in migration:

  1. modification time stamps
    1. migration issue only?
  2. trac tags
  3. tag lists (not really like toctree)

Sphinx access to docinfo metadata!topic/sphinx-dev/Hszmw8clhrM

Investigate in env.sphinxext.taglist looks like only specific metadata keys are read

Trac Macros that I use

TracNav(ReponameNav) : sidebar navigation panel

Not really equivalent to the Sphinx toctree:

  • multi document index, not needed at single doc level with Sphinx
  • will need manual organization as Trac is effectively flat and Sphinx uses a tree


Inpage content list, translate to:

.. contents:: :local:


Only a few of these

TagList + per-page tag listing

Need a Sphinx extension to handle this, maybe use standard top of doc fieldlist:

:tags: Red, Green, Blue

And/or extension (assuming can grab the page context and get the metadats tags on that page with local)

   .. taglist:: :local:


Trac taglists are dynamic and provide links to pages featuring those tags,

  • how to do that possible in Sphinx ?