We've created a new branch and are in the process of migrating all of
our documentation over to Sphinx. The process has gone well and we
have a working demo of the full system online. By converting to
Sphinx, we get the huge advantage of being on a standardized platform
that everyone can understand and contribute towards. All kinds of
wacky old code, some of it four or more years old, has been removed
(and we thank it for its service). The docs are now split into "Main
Documentation" and "API Reference". Because Sphinx allows very
flexible layout of docstring-generated documentation, "Main
Documentation" is shrinking and the docstrings used by "API
Reference", which is an all new section that replaces the old
"straight down modules" display, are growing dramatically, which means
more documentation is centralized across the site/pydocs and there's
less redundancy.
What we are now looking for with regards to the demo is:
- comments/suggestions regarding layout, styling. Some layout
changes were forced by Sphinx, and others (most) are improvements
that Sphinx allowed us to achieve. I'm not a CSS guru or a designer
so suggested patches to the CSS and templates would be welcome. If
Todd Grimason is out there, feel free to chime in :) .
- proofreaders. The content on the demo is maybe 60% of the way
there and we're combing through finding issues related to the Sphinx
conversion, as well as things that have just been wrong all along.
We would love to get patches against the doc build correcting as many
issues as possible.
- authors. No excuses now , we're on the most standard platform
there is for docs. If you have better verbiage for sections or
docstrings which aren't clear, are nonexistent (like many of the
dialects) or are out of date (theres lots), we want to see
suggestions. More elaborate suggestions regarding new sections and
organization are welcome too as the structure is completely open ended.
- people who understand LaTex to work on the PDF side of things.
This one's totally over my head as far as how to get a pdf file out of
this thing (pdflatex is fairly inscrutable on a mac).
Sphinx 0.6 is required, which at the time of this writing is not yet
released so you'll have to check out Sphinx from its mercurial
repository if you want to do builds.
View the content online at: http://www.sqlalchemy.org/docs/sphinxtest/
Checkout the SVN branch and do a build:
http://svn.sqlalchemy.org/sqlalchemy/branches/sphinx
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"sqlalchemy" 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/sqlalchemy?hl=en
-~----------~----~----~----~------~----~------~--~---
