Here are the suggestions that come to mind: - You should either get rid of, or (preferably) expand/replace the current top-level "table of contents". As it is currently, there is only one useful link in there (API reference) and the table of contents block waste way too much space for just one link. I liked the old condensed table of contents which fit entirely on the screen without scrolling.
- The vertical spacing between the <li> is slightly too large to my taste, making for too much scrolling. I'd prefer a spacing roughly equivalent to the old doc site. This issue might become mostly irrelevant if the first one is fixed. - Inside the "Object Relational Tutorial" section, the TOC is flat. The hierarchical one was better IMO. - The new API reference TOC is better IMO than the old one because it doesn't include all the classes. I always took a few sec to find what I wanted because there was too much information in there. - On the other hand, I find the TOC *inside* API reference sections to be lacking a reference to all public classes of the module, like there was in the old system, for example at: http://www.sqlalchemy.org/docs/05/sqlalchemy_schema.html Btw: there is no TOC in api/sqlalchemy/Database schema. On Wed, Dec 3, 2008 at 19:06, Michael Bayer <[EMAIL PROTECTED]> wrote: > > 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 -- Gaëtan de Menten http://openhex.org --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
