[sqlalchemy] Re: SQLAlchemy Sphinx Documentation Preview
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. On Dec 6, 6:44 am, Michael Bayer [EMAIL PROTECTED] wrote: 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. --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sqlalchemy] Re: SQLAlchemy Sphinx Documentation Preview
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. On Wed, Dec 3, 2008 at 11:36 PM, 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 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sqlalchemy] Re: SQLAlchemy Sphinx Documentation Preview
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 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sqlalchemy] Re: SQLAlchemy Sphinx Documentation Preview
well we have no control over any of thatI don't know that Sphinx search uses case insensitivity for full text searches. On Dec 5, 2008, at 11:53 AM, Jon Nelson wrote: 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 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sqlalchemy] Re: SQLAlchemy Sphinx Documentation Preview
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 lis, but their sub-items get a more cozy 1.2em. To me this
looks as it should.
Eric
On Dec 5, 9:23 am, Michael Bayer [EMAIL PROTECTED] wrote:
well we have no control over any of thatI don't know that Sphinx
search uses case insensitivity for full text searches.
On Dec 5, 2008, at 11:53 AM, Jon Nelson wrote:
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
--~--~-~--~~~---~--~~
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
-~--~~~~--~~--~--~---
[sqlalchemy] Re: SQLAlchemy Sphinx Documentation Preview
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.
On Dec 5, 7:48 pm, Eric Ongerth [EMAIL PROTECTED] wrote:
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 lis, but their sub-items get a more cozy 1.2em. To me this
looks as it should.
Eric
On Dec 5, 9:23 am, Michael Bayer [EMAIL PROTECTED] wrote:
well we have no control over any of thatI don't know that Sphinx
search uses case insensitivity for full text searches.
On Dec 5, 2008, at 11:53 AM, Jon Nelson wrote:
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
--~--~-~--~~~---~--~~
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
-~--~~~~--~~--~--~---
[sqlalchemy] Re: SQLAlchemy Sphinx Documentation Preview
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. --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sqlalchemy] Re: SQLAlchemy Sphinx Documentation Preview
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 -~--~~~~--~~--~--~---
[sqlalchemy] Re: SQLAlchemy Sphinx Documentation Preview
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 ulli 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
--~--~-~--~~~---~--~~
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
-~--~~~~--~~--~--~---
[sqlalchemy] Re: SQLAlchemy Sphinx Documentation Preview
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.
On Dec 4, 2008, at 9:25 AM, Michael Bayer wrote:
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 ulli 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
--~--~-~--~~~---~--~~
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
-~--~~~~--~~--~--~---
