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 sqlalchemy@googlegroups.com
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
-~----------~----~----~----~------~----~------~--~---

Reply via email to