From: Mike Bayer Date: Fri, 25 Nov 2011 21:17:16 +0000 (-0500) Subject: doc styling rework X-Git-Tag: rel_0_7_4~50 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6733a9bbddc9acb49d112fb169640456c6a14c9e;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git doc styling rework --- diff --git a/doc/build/core/index.rst b/doc/build/core/index.rst index 1e205da67d..7f9ad945a9 100644 --- a/doc/build/core/index.rst +++ b/doc/build/core/index.rst @@ -3,6 +3,11 @@ SQLAlchemy Core =============== +The breadth of SQLAlchemy’s SQL rendering engine, DBAPI integration, +transaction integration, and schema description services are documented here. +In contrast to the ORM’s domain-centric mode of usage, the SQL Expression +Language provides a schema-centric usage paradigm. + .. toctree:: :maxdepth: 3 diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index d347f05468..f999115620 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -4,9 +4,6 @@ SQL Expression Language Tutorial ================================ -Introduction -============= - The SQLAlchemy Expression Language presents a system of representing relational database structures and expressions using Python constructs. These constructs are modeled to resemble those of the underlying database as closely diff --git a/doc/build/orm/index.rst b/doc/build/orm/index.rst index fa14e3bea4..0c461fb6de 100644 --- a/doc/build/orm/index.rst +++ b/doc/build/orm/index.rst @@ -3,6 +3,11 @@ SQLAlchemy ORM =============== +Here, the Object Relational Mapper is introduced and fully described. If you +want to work with higher-level SQL which is constructed automatically for you, +as well as automated persistence of Python objects, proceed first to the +tutorial. + .. toctree:: :maxdepth: 3 diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index 4a1ad9e332..2a56b3013c 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -4,9 +4,6 @@ Object Relational Tutorial ========================== -Introduction -============ - The SQLAlchemy Object Relational Mapper presents a method of associating user-defined Python classes with database tables, and instances of those classes (objects) with rows in their corresponding tables. It includes a diff --git a/doc/build/static/docs.css b/doc/build/static/docs.css index e338590ad4..1169a8a975 100644 --- a/doc/build/static/docs.css +++ b/doc/build/static/docs.css @@ -1,248 +1,240 @@ +/* global */ + body { background-color: #FDFBFC; margin:38px; color:#333333; } -body, td { - font-family: verdana, sans-serif; - font-size:.9em; -} - -h1, h2, h3, h4, h5 { - font-family:Tahoma,Geneva,sans-serif; - font-weight:normal; - font-family:arial,Helvetica, sans-serif; - font-weight:bold; +a { + font-weight:normal; + text-decoration:none; } -h1 { - font-size:20px; - line-height:22px; - color: #222222; - font-family:arial,Helvetica, sans-serif; - font-weight:normal; - margin: 0; - padding: 0; -} -h1, #topnav h2 { - font-family:Tahoma,Geneva,sans-serif; - font-weight:normal; -} form { display:inline; } -p { - margin-top:10px; - margin-bottom:10px; -} - -a { - font-weight:normal; - text-decoration:none; -} +/* hyperlinks */ a:link, a:visited, a:active { - color:#0000FF; + /*color:#0000FF;*/ + color: #990000; } a:hover { - color:#700000; + color: #FF0000; + /*color:#700000;*/ + text-decoration:underline; } -strong a { - font-weight: bold; -} +/* paragraph links after sections. + These aren't visible until hovering + over the tag, then have a + "reverse video" effect over the actual + link + */ -.document { - border: solid 1px #ccc; +a.headerlink { + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; + visibility: hidden; } -.document h1, .document h2, .document h3, .document h4, .document h5 { - font-size: 1.4em; +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; } -.document img { - display:block; - margin: 0 auto; +a.headerlink:hover { + background-color: #990000; + color: white; } -.document h1 { - display:none; + +/* Container setup */ + +#docs-container { + max-width:1000px; } -/* standard page elements */ -#search { - float:right; +/* header/footer elements */ + +#docs-header h1 { + font-size:20px; + color: #222222; + margin: 0; + padding: 0; } -#searchform { - padding:20px; +#docs-header { + font-family:Verdana,sans-serif; + + font-size:.9em; + } -#navbanner { +#docs-top-navigation, +#docs-bottom-navigation { + font-family: Verdana, sans-serif; + background-color: #FBFBEE; + border: solid 1px #CCC; + padding:10px; + font-size:.8em; } -#pagecontrol { - float:right; - width:300px; +#docs-top-navigation { + margin:10px 0px 10px 0px; + line-height:1.2em; } -#pagecontrol ul { - padding:0; - margin:0; +.docs-navigation-links { + font-family:Verdana,sans-serif; } -#pagecontrol li { - font-size:.9em; - list-style-type:none; - margin:0px; - padding:1px 8px; + +#docs-bottom-navigation { + float:right; + margin: 1em 0 1em 5px; } -#topnav { - background-color: #fbfbee; - border: solid 1px #ccc; - padding:10px; - margin:10px 0px 10px 0px; - display:block; +#docs-copyright { + font-size:.85em; + padding:5px 0px; } -#topnav .prevnext { - padding: 5px 0px 0px 0px; - /*font-size: 0.8em*/ +#docs-header h1, +#docs-top-navigation h1, +#docs-top-navigation h2 { + font-family:Tahoma,Geneva,sans-serif; + font-weight:normal; } -#topnav h2 { - margin:8px 4px 0px 5px; +#docs-top-navigation h2 { + margin:16px 4px 7px 5px; font-size:1.6em; - font-weight:normal; - line-height:1.6em; } -#topnav h3 { - font-weight: bold; - font-size: 1.4em; - margin:0px; - display:inline; +#docs-search { + float:right; } -#navbanner li, -li.toctree-l1, -li.toctree-l1 li -{ - list-style-type:disc; - margin:0px; - padding:1px 8px; +#docs-top-page-control { + float:right; + width:350px; } - -#topnav li ul, -li.toctree-l1 ul -{ - padding:0px 0px 0px 20px; +#docs-top-page-control ul { + padding:0; + margin:0; } -#topnav li ul li li, -li.toctree-l1 ul li li { +#docs-top-page-control li { + font-size:.9em; + list-style-type:none; + padding:1px 8px; } -.versionheader { - margin-top: 0.5em; -} -.versionnum { + +#docs-container .version-num { font-weight: bold; } -.prerelease { - border: solid #c25757 2px; - border-radius: 4px; - -moz-border-radius: 4px; - -webkit-border-radius: 4px; - background-color: #c21a1a; - color: white; - padding: 0.05em 0.2em; -} -.bottomnav { - background-color:#FBFBEE; - border:1px solid #CCCCCC; - float:right; - margin: 1em 0 1em 5px; - padding:10px; -} -.totoc { +/* content container, sidebar */ -} +#docs-body-container { + background-color:#EFEFEF; + border: solid 1px #CCC; -.doc_copyright { - font-size:.85em; - padding:10px 0px 10px 0px; } -/* ReST specific section padding */ +#docs-body, +#docs-sidebar + { + /*font-family: helvetica, arial, sans-serif; + font-size:.9em;*/ + + font-family: Verdana, sans-serif; + font-size:.85em; + line-height:1.5em; -.section ul { - padding: 0 0 0 25px; } -.section { - line-height: 1.5em; - padding:0px 10px 20px 10px; - margin:10px 0px 0px; +#docs-sidebar > ul { + font-size:.85em; } -.section .section { - margin:0px 0px 0px 0px; - padding: 0px; +#docs-sidebar { + float:left; + width:212px; + padding: 10px 0 0 15px; + font-size:.85em; } -.section .section .section { - margin:0px 0px 0px 20px; +#docs-sidebar h3, #docs-sidebar h4 { + background-color: #DDDDDD; + color: #222222; + font-family: Verdana,sans-serif; + font-size: 1.1em; + font-weight: normal; + margin: 10px 0 0 -15px; + padding: 5px 10px 5px 10px; + text-shadow: 1px 1px 0 white; + width:210px; } -.section .section .section .section { - margin:0px 0px 0px 20px; +#docs-sidebar h3 a, #docs-sidebar h4 a { + color: #222222; +} +#docs-sidebar ul { + margin: 10px 10px 10px 0px; + padding: 0; + list-style: none outside none; } -/* special index sections */ -div#sqlalchemy-documentation { - font-size:.95em; -} -div#sqlalchemy-documentation em { - font-style:normal; +#docs-sidebar ul ul { + margin-bottom: 0; + margin-top: 0; + list-style: square outside none; + margin-left: 20px; } -div#sqlalchemy-documentation .rubric{ - font-size:14px; - background-color:#EEFFEF; - padding:5px; - border:1px solid #BFBFBF; + +#docs-body { + background-color:#FFFFFF; + padding:1px 10px 10px 10px; } -div#sqlalchemy-documentation a, div#sqlalchemy-documentation li { - padding:5px 0px; + +#docs-body.withsidebar { + margin: 0 0 0 230px; + border-left:3px solid #DFDFDF; } -div#getting-started { - border-bottom:1px solid; +#docs-body h1, +#docs-body h2, +#docs-body h3, +#docs-body h4 { + font-family:Helvetica, Arial, sans-serif; } -div#sqlalchemy-documentation div#sqlalchemy-orm { - float:left; - width:48%; +#docs-body h1 { + /* hide the

for each content section. */ + display:none; + font-size:1.8em; } -div#sqlalchemy-documentation div#sqlalchemy-core { - float:left; - width:48%; - margin:0; - padding-left:10px; - border-left:1px solid; +#docs-body h2 { + font-size:1.6em; } -div#dialect-documentation { - border-top:1px solid; - clear:left; +#docs-body h3 { + font-size:1.4em; } /* SQL popup, code styles */ @@ -250,29 +242,41 @@ div#dialect-documentation { .highlight { background:none; } -pre { + +#docs-container pre { + font-size:1.2em; +} + +#docs-container .pre { + font-size:1.1em; +} + +#docs-container pre { background-color: #f0f0f0; border: solid 1px #ccc; + box-shadow: 2px 2px 3px #DFDFDF; padding:10px; - margin: 5px 5px 5px 5px; + margin: 5px 0px 5px 0px; overflow:auto; line-height:1.3em; } .popup_sql, .show_sql { - background-color: #fbfbee; - padding:0px 10px; - margin:0px -10px; + background-color: #FBFBEE; + padding:5px 10px; + margin:10px -5px; + border:1px dashed; } -.sql_link +/* the [SQL] links used to display SQL */ +#docs-container .sql_link { font-weight:normal; font-family: arial, sans-serif; - text-transform: uppercase; - font-size: 0.9em; - color:#666; + font-size:.9em; + text-transform: uppercase; + color:#990000; border:1px solid; padding:1px 2px 1px 2px; margin:0px 10px 0px 15px; @@ -280,20 +284,21 @@ pre { line-height:1.2em; } -#docs a.sql_link, .sql_link +#docs-container a.sql_link, +#docs-container .sql_link { text-decoration: none; padding:1px 2px; } -#docs a.sql_link:hover { +#docs-container a.sql_link:hover { text-decoration: none; color:#fff; border:1px solid #900; background-color: #900; } -/* other assorted ReST styles */ +/* docutils-specific elements */ th.field-name { text-align:right; @@ -306,9 +311,9 @@ div.note, div.warning, p.deprecated, div.topic { div.admonition, div.topic, p.deprecated { border:1px solid #CCCCCC; - margin:5px 5px 5px 5px; - padding:5px 5px 5px 35px; + padding:5px 10px; font-size:.9em; + box-shadow: 2px 2px 3px #DFDFDF; } div.warning .admonition-title { @@ -331,7 +336,7 @@ dl.class > dt, dl.exception > dt { background-color:#F0F0F0; - margin:0px -10px; + margin:25px -10px 10px 10px; padding: 0px 10px; } @@ -381,16 +386,50 @@ tt { padding:0 1px; } -@media print { - #nav { display: none; } - #pagecontrol { display: none; } - #topnav .prevnext { display: none; } - .bottomnav { display: none; } - .totoc { display: none; } - #topnav ul li a { text-decoration: none; color: #000; } -} - /* syntax highlighting overrides */ .k, .kn {color:#0908CE;} .o {color:#BF0005;} .go {color:#804049;} + + +/* special "index page" sections + with specific formatting +*/ + +div#sqlalchemy-documentation { + font-size:.95em; +} +div#sqlalchemy-documentation em { + font-style:normal; +} +div#sqlalchemy-documentation .rubric{ + font-size:14px; + background-color:#EEFFEF; + padding:5px; + border:1px solid #BFBFBF; +} +div#sqlalchemy-documentation a, div#sqlalchemy-documentation li { + padding:5px 0px; +} + +div#getting-started { + border-bottom:1px solid; +} + +div#sqlalchemy-documentation div#sqlalchemy-orm { + float:left; + width:48%; +} + +div#sqlalchemy-documentation div#sqlalchemy-core { + float:left; + width:48%; + margin:0; + padding-left:10px; + border-left:1px solid; +} + +div#dialect-documentation { + border-top:1px solid; + /*clear:left;*/ +} diff --git a/doc/build/templates/layout.mako b/doc/build/templates/layout.mako index a5e3d17c84..d34e4ef38a 100644 --- a/doc/build/templates/layout.mako +++ b/doc/build/templates/layout.mako @@ -1,6 +1,32 @@ ## coding: utf-8 + +<%doc> + Structural elements are all prefixed with "docs-" + to prevent conflicts when the structure is integrated into the + main site. + + docs-container -> + docs-header -> + docs-search + docs-version-header + docs-top-navigation + docs-top-page-control + docs-navigation-banner + docs-body-container -> + docs-sidebar + docs-body + docs-bottom-navigation + docs-copyright + + <%inherit file="${context['mako_layout']}"/> +<% +withsidebar = bool(toc) and current_page_name != 'index' +%> + +
+ <%block name="headers"> @@ -37,29 +63,36 @@ % endif -

${docstitle|h}

+
+

${docstitle|h}

- + -
- Release: ${release} | Release Date: ${release_date} - % if not version.startswith(versions[0][0]): -
- The current version of SQLAlchemy is ${versions[0][0]}. View current SQLAlchemy Documentation +
+ Release: ${release} | Release Date: ${release_date} + + % if self.attr.site_layout: + | Download PDF + % endif + + % if self.attr.site_layout and not version.startswith(versions[0][0]): +
+ The current version of SQLAlchemy is ${versions[0][0]}. View current SQLAlchemy Documentation +
+ % endif
- % endif +
-
-
-
+
+
    % if prevtopic:
  • Prev: @@ -81,8 +114,9 @@ Search:
-

- % if display_toc and \ - not current_page_name.startswith('index') and \ - not current_page_name.startswith('contents'): - ${toc} - % endif -
+ -
-
+
+ +% if withsidebar: +
+

Table of Contents

+ ${toc} + + % if prevtopic: +

Previous Topic

+

+ ${prevtopic['title']} +

+ % endif + % if nexttopic: +

Next Topic

+

+ ${nexttopic['title']} +

+ % endif + +

Quick Search

+

+

+ + + +
+

+ +
+% endif + +
${next.body()}
+
<%block name="footer"> -
+