On Sat, Nov 29, 2008 at 11:22 AM, Michael Bayer <[EMAIL PROTECTED]> wrote:
>
> hello sphinxers -
>
> im looking into the inevitable sphinx transition for SQLAlchemy
> documentation. So far I'm clearing most hurdles. The most elaborate
> though is how to handle our code blocks.
>
> In our docs, we have some special directives in our code blocks. One
> are just doctest directives, and I'm surprised Sphinx isn't filtering
> these out unless I'm missing some config option somehwere, and the
> other is our little "SQL" windows which you can see all over our
> documentation on the website.
>
> So I need to write a processor that handles "source code examples"
> like this:
>
> {sql}>>> conn.execute(addresses.insert(), [ # doctest: +ELLIPSIS
> ... {'user_id': 1, 'email_address' : '[EMAIL PROTECTED]'},
> ... {'user_id': 1, 'email_address' : '[EMAIL PROTECTED]'},
> ... {'user_id': 2, 'email_address' : '[EMAIL PROTECTED]'},
> ... {'user_id': 2, 'email_address' : '[EMAIL PROTECTED]'},
> ... ])
> INSERT INTO addresses (user_id, email_address) VALUES (?, ?)
> [[1, '[EMAIL PROTECTED]'], [1, '[EMAIL PROTECTED]'], [2, '[EMAIL
> PROTECTED]'],
> [2, '[EMAIL PROTECTED]']]
> COMMIT
> {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
>
> my processor would basically filter out the "# doctest" directives,
> stick the SQL code down to the {stop} into a <div> with some
> jqueryness applied, and the {sql} directive is a clue as to where the
> [SQL] link gets emitted. All the Python in between would go through
> the PygmentsBridge which nicely knows how to handle the >>> for us.
>
> I looked into creating custom docutils directives to replace our ad-
> hoc {sql}/{stop} tags, but it wasn't clear to me how this would work
> or produce the kinds of results I want, since I'm really outputting
> HTML that correponds to units that I don't think really exist within
> the docutils model.
>
> It seems much easier to just keep all the markup as is and just build
> my own HTMLTranslator.visit_literal_block() method. I'd basically
> rewrite the method to call upon the same highlighting services but
> just within a more elaborate system of breaking out the text.
>
> So the questions are:
>
> 1. am i unaware of some entirely better way to deal with our source
> code blocks, including the doctest directives and custom SQL popups ?
> 2. is this reasonable to subclass HTMLTranslator in this way?
> 3. what should the approach to cleaning up the codeblocks be when
> using LatexBuilder ?
Making a `pycon+sql` Pygments lexer & formatter is an option I
considered when I was looking at porting the SA tutorials from
markdown to reST. I don't think sphinx would need to be involved at
all in that approach, beyond setting .. highlight:: pycon+sql or the
occasional .. code-block:: override in the .rst sources.
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
