[sqlalchemy] Re: Small note on reading SA docs
Oh, I was not aware. The 05 docs is, as you say, addressing some of my points. Thanks On May 22, 1:14 am, semafor jo...@drange.net wrote: Hi. Currently, the documentation for SA is not easy for the eyes. Usinghttp://www.sqlalchemy.org/docs/04/sqlalchemy_engine.htmlas an example, there are ways to improve this: * 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. 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. * 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. * De-emphasizing back to section top. The link is almost the same size as the class ancestor (constructor argument), which requires effort to separate. * The darkcell div is indeed superfluous. One could create the same effect of division with white space and/or horizontal bordering. * Emphasizing class properties and module includes. The default indentation of definition data is not sufficient. * Generally using white space more efficiently. I could happily assist someone in charge of the site, or do it myself. For the latter, I probably need some approval, branches of both sqlalchemy and sqlalchemyorg repos, or both? Anyway, SA is an impressive project. Kind regards, Jonas. --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sqlalchemy] Re: Small note on reading SA docs
On Friday 22 May 2009 01.59:13 Michael Bayer wrote: 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. Since removing them entirely is an option for you, perhaps just completely remove them from search engines via robots.txt? (And have a page linking to and describing the 0.3/0.4 docs in a way so that people searching for them explicitly still find them.) cheers -- vbi -- The most interesting [DNS weirdness] is that when I visit the Asus website two Asus IPs (one in the US, one in Taiwan) will query my nameserver for the . record for an entire week. -- Koos van den Hout signature.asc Description: This is a digitally signed message part.
[sqlalchemy] Re: Small note on reading SA docs
I've had quite the opposite experience with SQLAlchemy's documentation, and I just started using it for a couple of small projects about two weeks ago. Once I was accustomed to the site layout, it became reasonably easy to find what I was looking for. Specifically, I've been using the integrated search, and while it isn't the best for somewhat more advanced multi-keyword matches, it seems that mixing keywords found from Google (even if it does turn up things from 0.3 and up :) with the site search works pretty well. The greatest problem I can see with the docs is that they're quite voluminous. Frankly, that's a *good* problem to have. :) Keep up the great work! Regards, Benjamin --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sqlalchemy] Re: Small note on reading SA docs
Bobby Impollonia wrote: 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. The simplest thing to do is to append: Disallow: /docs/04/ Disallow: /docs/03/ agreed, this is done. --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sqlalchemy] Re: Small note on reading SA docs
Bobby Impollonia wrote: I also noticed that your current robots.txt file disallows indexing of anything under /trac/. It would nice to let google index bugs in trac so that someone who searches google for sqlalchemy help can come across an extant bug describing their problem. In addition, you have links on the front page (changelog and what's new) that go to urls under /trac/ , so google will not follow those links due to your robots.txt. I was probably concerned about load at some point but I've allowed /trac now. --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sqlalchemy] Re: Small note on reading SA docs
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 -~--~~~~--~~--~--~---
[sqlalchemy] Re: Small note on reading SA docs
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. The simplest thing to do is to append: Disallow: /docs/04/ Disallow: /docs/03/ to the file: http://www.sqlalchemy.org/robots.txt This tells google (and all well-behaved search engines) not to index those urls (and anything under them). The next time the googlebot comes through, it will see the new robots.txt and remove those pages from its index. This will take a couple weeks at most. You can learn more about robots.txt here: http://www.robotstxt.org/ The disadvantage to doing it that way is that you will lose the google juice (pagerank) for inbound links to the old documentation. An alternative approach that gets around this to use a link rel=canonical ... tag in the head of each page of the 04 and 03 documentation pointing to the corresponding page of 05 documentation as its canonical url. By doing this, you are claiming that the 04/ 03 documentation pages are duplicates of the corresponding 05 pages. Google juice from inbound links to an old documentation page will accrue to the appropriate 05 documentation page instead. However, strictly speaking, the different versions aren't quite duplicates, so you might be pushing the boundaries of what is allowed a bit by claiming they are. Here is more info on rel=canonical from google: http://googlewebmastercentral.blogspot.com/2009/02/specify-your-canonical.html A similar approach would be to do a 301 redirect from each old documentation page to the corresponding 05 documentation page, but only if the visitor is the googlebot. This is straightforward to implement with mod_rewrite (the googlebot can be recognized by its user-agent string), but probably a bad idea since google usually considers it cloaking to serve different content to the googlebot than to regular visitors. You should also consider submitting an XML sitemap to google via the google webmaster tools. This allows you to completely spell out for them the structure of the site and what you want indexed. I also noticed that your current robots.txt file disallows indexing of anything under /trac/. It would nice to let google index bugs in trac so that someone who searches google for sqlalchemy help can come across an extant bug describing their problem. In addition, you have links on the front page (changelog and what's new) that go to urls under /trac/ , so google will not follow those links due to your robots.txt. --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
[sqlalchemy] Re: Small note on reading SA docs
Rereading what you posted, by such a prominent place on Google, did you mean specifically the .4 and .3 links that show up below sqlalchemy when www.sqlalchemy.org is returned in the search results? Those are what google calls sitelinks. You can tell them not to use certain pages as sitelinks via the google webmaster tools. They'll remove them, but they don't get replaced so you will have two fewer sitelinks then. On Thu, May 21, 2009 at 8:03 PM, Bobby Impollonia bob...@gmail.com wrote: 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. The simplest thing to do is to append: Disallow: /docs/04/ Disallow: /docs/03/ to the file: http://www.sqlalchemy.org/robots.txt This tells google (and all well-behaved search engines) not to index those urls (and anything under them). The next time the googlebot comes through, it will see the new robots.txt and remove those pages from its index. This will take a couple weeks at most. You can learn more about robots.txt here: http://www.robotstxt.org/ The disadvantage to doing it that way is that you will lose the google juice (pagerank) for inbound links to the old documentation. An alternative approach that gets around this to use a link rel=canonical ... tag in the head of each page of the 04 and 03 documentation pointing to the corresponding page of 05 documentation as its canonical url. By doing this, you are claiming that the 04/ 03 documentation pages are duplicates of the corresponding 05 pages. Google juice from inbound links to an old documentation page will accrue to the appropriate 05 documentation page instead. However, strictly speaking, the different versions aren't quite duplicates, so you might be pushing the boundaries of what is allowed a bit by claiming they are. Here is more info on rel=canonical from google: http://googlewebmastercentral.blogspot.com/2009/02/specify-your-canonical.html A similar approach would be to do a 301 redirect from each old documentation page to the corresponding 05 documentation page, but only if the visitor is the googlebot. This is straightforward to implement with mod_rewrite (the googlebot can be recognized by its user-agent string), but probably a bad idea since google usually considers it cloaking to serve different content to the googlebot than to regular visitors. You should also consider submitting an XML sitemap to google via the google webmaster tools. This allows you to completely spell out for them the structure of the site and what you want indexed. I also noticed that your current robots.txt file disallows indexing of anything under /trac/. It would nice to let google index bugs in trac so that someone who searches google for sqlalchemy help can come across an extant bug describing their problem. In addition, you have links on the front page (changelog and what's new) that go to urls under /trac/ , so google will not follow those links due to your robots.txt. --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
