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 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.
--
Gaëtan de Menten
http://openhex.org
>
> 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 agree - unfortunately this so far seems to be a limitation of
Sphinx. I like the table of contents on individual documentation
pages where its meaningful, and since every page uses the same
template, you have no choice but to display the ${toc} variable, which
is provided by Sphinx as a string with the full <ul><li> structure
inside of it. If you take a look at the sidebar on docs.python.org,
you'll see its the exact same thing. I can perhaps make the display
of ${toc} conditional based on the name of the page (i.e. index). I
really wish Sphinx would provide the ${toc} as a Python structure
which can be manipulated.
> I liked the
> old condensed table of contents which fit entirely on the screen
> without scrolling.
yeah we don't have a lot of options for that and the index page is
where I've been the most frustrated.
>
>
> - 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.
I was trying to get the <li> to be exactly the same and was not
successful. I'm not that good at CSS to figure it out (though we're
trying not to use any pixel sizes...maybe we need to just do that).
> - Inside the "Object Relational Tutorial" section, the TOC is flat.
> The hierarchical one was better IMO.
thats a bug, i need to fix the headings in the tutorial
Otherwise they look nice and I'm sure will look nicer-yet as time goes on!
--
Jon
>
> Oh yeah, and in Main Documentation (at least) you have some <ul
> class="simple"> lists nested inside of <blockquote> elements, which is
> resulting in some of your lists being much farther indented than
> others, without a good visual reason why. Seems like the difference
> could be eliminated.
sphinx (actually docutils) creates that structure; unless we've done
something wrong in the rest markup, we can't change it without parsing
it and reconstructing it (which seems like overkill to me, since CSS
selectors can usually find things). not sure what is prompting it
to create a <blockquote> though.