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 ?
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
