SQLAlchemy Sphinx Documentation Preview

[Michael Bayer]

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

[Gaetan de Menten]

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.

--
Gaëtan de Menten
http://openhex.org

[Michael Bayer]

On Dec 4, 2008, at 4:21 AM, Gaetan de Menten wrote:

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

[Michael Bayer]

I've made all of these changes up on the site. The <li> issue was a
pixel-based padding already so I just reduced that.

[Eduardo Schettino]

Hi,

There are some sphinx system messages on:
http://www.sqlalchemy.org/docs/sphinxtest/intro.html


Reference Documentation¶

*

System Message: WARNING/2
(/home/classic/dev/sphinx/doc/build/intro.rst)
undefined label: datamapping – if you don't give a link
caption the label must precede a section header.
- A comprehensive walkthrough of major ORM patterns and techniques.
*

System Message: WARNING/2
(/home/classic/dev/sphinx/doc/build/intro.rst)
undefined label: session – if you don't give a link caption
the label must precede a section header.
- A detailed description of SQLAlchemy's Session object
*

System Message: WARNING/2
(/home/classic/dev/sphinx/doc/build/intro.rst)
undefined label: engines – if you don't give a link caption
the label must precede a section header.
- Describes SQLAlchemy's database-connection facilities,
including connection documentation and working with connections and
transactions.
*

System Message: WARNING/2
(/home/classic/dev/sphinx/doc/build/intro.rst)
undefined label: pooling – if you don't give a link caption
the label must precede a section header.
- Further detail about SQLAlchemy's connection pool library.

[Jon Nelson]

The searching is a bit weird.
If I search for Adjacency I get no results. If I search for adjacency
(all lower case) I get results, the first of which has an upper-cased
Adjacency.

Otherwise they look nice and I'm sure will look nicer-yet as time goes on!

--
Jon

[Michael Bayer]

well we have no control over any of that....I don't know that Sphinx
search uses case insensitivity for full text searches.

[Eric Ongerth]

Mike,

Gaetan's right -- I just viewed the site a day after you (Mike) said
that the <li> issue had been fixed, but they're still too widely
spaced for sure. There are several conflicting (well ok, inheriting/
overriding) settings of line-height across the various css files, and
it does not appear that padding is actually the problem.

Here, make the following change to site_docs.css and see what you
think.

current:

a { line-height: 1.2em; }

replace this with:

li li { line-height: 1.2em; }

This leaves in place the 1.3em that's inherited from above for the
main <li>s, but their sub-items get a more cozy 1.2em. To me this
looks as it should.

Eric

[Eric Ongerth]

Forgot to add that I can't see much reason for links to be given a
line-height that would be any different from the text that surrounds
them -- at least not on the TOC page. That's why I felt free to scrap
the 'a' rule and put the 'li li' in the same spot. If the 'a' rule is
necessary for other pages then my suggestion could be an addition
instead of a replacement.

[Eric Ongerth]

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.

I sent new association_proxy docs via jek; hopefully you'll find them
worthwhile in total or in part.

[Michael Bayer]

On Dec 5, 2008, at 11:00 PM, Eric Ongerth wrote:

>
> 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.

[Eric Ongerth]

You're right about CSS selectors; the simple fix for this without re-
generating any source, is just to instruct the browser to not double
up on the indentation when it sees a ul nested in a blockquote. Hey
wait, the problem is already fixed. Looks great today. The lists
too; thanks for the changes.