On May 21, 2009, at 7:14 PM, semafor wrote:
>
> Hi.
>
> Currently, the documentation for SA is not easy for the eyes. Using
> http://www.sqlalchemy.org/docs/04/sqlalchemy_engine.html as an
> example, there are ways to improve this:
thats not a good example to choose at all as the documentation has
since been migrated to Sphinx, the templates have been rewritten, and
completely new stylesheets developed which are generally the stock
Sphinx sheets, with modifications to suit our slightly different
navigation and color scheme. The current docs are at:
http://www.sqlalchemy.org/docs/05/index.html
the 0.4 series should be considered obsolete. if I were to change
something with those docs, its that they'd be removed from the site
entirely. otherwise if you have any advice on how to get 0.4/0.3
delisted from such a prominent place on Google, that would be
appreciated.
>
> * Quasi syntax highlighting the function and it's arguments.
>
> Having "def create(self, entity, **kwargs)" all in bold is making it
> hard to browse through the functions by name as, at least, I often do.
this is fixed in the current sphinx docs.
>
> I also takes some effort separating the arguments from each other. For
> instance, "close_with_result=False" is also all in bold. "False"
> should undoubtedly be of a different format than the argument name.
AFAIK Sphinx and/or docutils doesn't support this (the markup
generated is hardwired into docutils) - as an example you can see it
on the Python site at
http://docs.python.org/library/platform.html#module-platform
.
> * Differentiate class documentation from function documentation.
> Today, the class header is just ~2px larger than the function header,
> i.e., not a big enough deviation. Using 30%+ larger header or wrapping
> it in a styled box should do it.
we generally list out functions and classes in entirely different
collections. docutils seems to generate different styles for classes
and functions. It does put the word "function" or "class" and the
Python docs don't seem to make any stylistic distinctions otherwise.
> * De-emphasizing "back to section top". The link is almost the same
> size as the class ancestor (constructor argument), which requires
> effort to separate.
that link does not exist in the Sphinx version of the documentation.
> * The "darkcell" div is indeed superfluous. One could create the same
> effect of division with white space and/or horizontal bordering.
the "gray" background is only used for code examples and as a
background for the function/class signature, and we no longer have
large tracts of text written on a gray background. the latter is
derived from what the Python documentation does for section headers.
> * Emphasizing class properties and module includes. The default
> indentation of definition data is not sufficient.
>
> * Generally using white space more efficiently.
since these are somewhat vague comments I would ask that you consider
the current Sphinx documentation for these attributes.
--~--~---------~--~----~------------~-------~--~----~
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
sqlalchemy+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/sqlalchemy?hl=en
-~----------~----~----~----~------~----~------~--~---
