Commits

Mike Bayer  committed 80a553d

- add a new "documentation overview" page. rip off a project widely known
to start with "Dj".

  • Participants
  • Parent commits 4efe203

Comments (0)

Files changed (9)

File doc/build/conf.py

 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = 'contents'
 
 # General information about the project.
 project = u'SQLAlchemy'

File doc/build/contents.rst

+.. _contents:
+
+Table of Contents
+=================
+
+Full table of contents.  For a high level overview of all
+documentation, see :ref:`index_toplevel`.
+
+.. toctree::
+    :maxdepth: 3
+
+    intro
+    orm/index
+    core/index
+    dialects/index
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`search`

File doc/build/core/schema.rst

 
 .. module:: sqlalchemy.schema
 
+
+.. _metadata_describing:
+
 Describing Databases with MetaData
 ==================================
 
     :undoc-members:
     :show-inheritance:
 
+
+.. _metadata_defaults:
+
 Column Insert/Update Defaults
 ==============================
 
 =================================
 
 .. _metadata_foreignkeys:
+.. _metadata_constraints:
 
 Defining Foreign Keys
 ---------------------
 .. autoclass:: Index
     :show-inheritance:
 
+.. _metadata_ddl:
+
 Customizing DDL
 ===============
 

File doc/build/core/types.rst

 typically accept a type class or instance; ``Integer`` is equivalent
 to ``Integer()`` with no construction arguments in this case.
 
+.. _types_generic:
+
 Generic Types
 -------------
 
    :show-inheritance:
    :members:
 
+.. _types_sqlstandard:
+
 SQL Standard Types
 ------------------
 
 .. autoclass:: VARCHAR
   :show-inheritance:
 
+.. _types_vendor:
 
 Vendor-Specific Types
 ---------------------
         Column('col2', TEXT(charset='latin1'))
     )
 
+.. _types_custom:
+
 Custom Types
 ------------
 
    :inherited-members:
    :show-inheritance:
 
+.. _types_api:
+
 Base Type API
 --------------
 

File doc/build/dialects/index.rst

     sybase
 
 
+

File doc/build/index.rst

-Table of Contents
-=================
+.. _index_toplevel:
 
-.. toctree::
-    :maxdepth: 2
+========================
+SQLAlchemy Documentation
+========================
 
-    intro
-    orm/index
-    core/index
-    dialects/index
+Getting Started
+===============
 
-Indices and tables
-------------------
+A high level view and getting set up.
 
-* :ref:`genindex`
-* :ref:`search`
+:ref:`Overview <overview>` | 
+:ref:`Installation Guide <installation>` |
+:ref:`Migration from 0.6 <migration>`
+
+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.
+
+* **Read this first:**
+  :doc:`orm/tutorial`
+
+* **ORM Configuration:**
+  :doc:`Mapper Configuration <orm/mapper_config>` |
+  :doc:`Relationship Configuration <orm/relationships>` |
+  :doc:`Inheritance Mapping <orm/inheritance>` |
+  :doc:`Advanced Collection Configuration <orm/collections>`
+
+* **Configuration Extensions:**
+  :doc:`Declarative Extension <orm/extensions/declarative>` |
+  :doc:`Association Proxy <orm/extensions/associationproxy>` |
+  :doc:`Hybrid Attrbutes <orm/extensions/hybrid>` |
+  :doc:`Mutable Scalars <orm/extensions/mutable>` |
+  :doc:`Ordered List <orm/extensions/orderinglist>`
+
+* **ORM Usage:**
+  :doc:`Session Usage and Guidelines <orm/session>` |
+  :doc:`Query API reference <orm/query>` |
+  :doc:`Relationship Loading Techniques <orm/loading>`
+
+* **Extending the ORM:**
+  :doc:`ORM Event Interfaces <orm/events>` |
+  :doc:`Internals API <orm/internals>`
+
+* **Other:**
+  :doc:`Introduction to Examples <orm/examples>` |
+  :doc:`Deprecated Event Interfaces <orm/deprecated>` |
+  :doc:`ORM Exceptions <orm/exceptions>` |
+  :doc:`Horizontal Sharding <orm/extensions/horizontal_shard>` |
+  :doc:`SQLSoup <orm/extensions/sqlsoup>`
+
+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.
+
+* **Read this first:**
+  :doc:`core/tutorial`
+
+* **All the Built In SQL:**
+  :doc:`SQL Expression API <core/expression_api>`
+
+* **Engines, Connections, Pools:**
+  :doc:`Engine Configuration <core/engines>` |
+  :doc:`Connections, Transactions <core/connections>` |
+  :doc:`Connection Pooling <core/pooling>`
+
+* **Schema Definition:**
+  :ref:`Tables and Columns <metadata_describing>` |
+  :ref:`Database Introspection (Reflection) <metadata_reflection>` |
+  :ref:`Insert/Update Defaults <metadata_defaults>` |
+  :ref:`Constraints and Indexes <metadata_constraints>` |
+  :ref:`Using Data Definition Language (DDL) <metadata_ddl>` 
+
+* **Datatypes:**
+  :ref:`Overview <types_toplevel>` | 
+  :ref:`Generic Types <types_generic>` | 
+  :ref:`SQL Standard Types <types_sqlstandard>` |
+  :ref:`Vendor Specific Types <types_vendor>` |
+  :ref:`Building Custom Types <types_custom>` |
+  :ref:`API <types_api>` 
+
+* **Extending the Core:**
+  :doc:`SQLAlchemy Events <core/event>` |
+  :doc:`Core Event Interfaces <core/events>` |
+  :doc:`Creating Custom SQL Constructs <core/compiler>` |
+  :doc:`Internals API <core/internals>`
+
+* **Other:**
+  :doc:`Serializing Expressions <core/serializer>` |
+  :doc:`core/interfaces` |
+  :doc:`core/exceptions`
+
+
+Dialect Documentation
+======================
+
+The **dialect** is the system SQLAlchemy uses to communicate with various types of DBAPIs and databases.  This section describes notes, options, and
+usage patterns regarding individual dialects.
+
+:doc:`dialects/drizzle` |
+:doc:`dialects/firebird` |
+:doc:`dialects/informix` |
+:doc:`dialects/maxdb` |
+:doc:`dialects/access` |
+:doc:`dialects/mssql` |
+:doc:`dialects/mysql` |
+:doc:`dialects/oracle` |
+:doc:`dialects/postgresql` |
+:doc:`dialects/sqlite` |
+:doc:`dialects/sybase`
+
+

File doc/build/intro.rst

 .. _overview_toplevel:
 
-=======================
-Overview / Installation
-=======================
+========
+Overview
+========
+
+.. _overview:
 
 Overview
 ========
 
-
 The SQLAlchemy SQL Toolkit and Object Relational Mapper
 is a comprehensive set of tools for working with
 databases and Python. It has several distinct areas of
 as it is used within object-relational configurations and
 queries.
 
+.. _doc_overview:
+
 Documentation Overview
 ======================
 
 
 In :ref:`core_toplevel`, the breadth of SQLAlchemy's SQL and database
 integration and description services are documented, the core of which is the
-SQL Expression language.  The SQL Expression Language is a toolkit all its own,
-independent of the ORM package, which can be used to construct manipulable SQL
+SQL Expression language.  The SQL Expression Language is a toolkit all its own, independent of the ORM package, which can be used to construct manipulable SQL
 expressions which can be programmatically constructed, modified, and executed,
-returning cursor-like result sets.  In contrast to the ORM's domain-centric 
+returning cursor-like result sets.  In contrast to the ORM's domain-centric
 mode of usage, the expression language provides a schema-centric usage
 paradigm.  New users should begin here with :ref:`sqlexpression_toplevel`.
-SQLAlchemy engine, connection, and pooling services are also described in 
+SQLAlchemy engine, connection, and pooling services are also described in
 :ref:`core_toplevel`.
 
-In :ref:`dialect_toplevel`, reference documentation for all provided 
+In :ref:`dialect_toplevel`, reference documentation for all provided
 database and DBAPI backends is provided.
 
 Code Examples
 constructs as well as the ORM on the wiki.  See
 `<http://www.sqlalchemy.org/trac/wiki/UsageRecipes>`_.
 
-Installing SQLAlchemy
-======================
+.. _installation:
+
+Installation Guide
+==================
+
+SQLAlchemy builds using the standard `Python Distutils <http://docs.python.org/distutils/>`_ approach.   
+
+Installing with setuptools or pip
+----------------------------------
 
 Installing SQLAlchemy from scratch is most easily achieved with `setuptools
 <http://pypi.python.org/pypi/setuptools/>`_, or alternatively
-`pip <http://pypi.python.org/pypi/pip/>`_. Assuming it's installed, just run
-this from the command-line:
+`pip <http://pypi.python.org/pypi/pip/>`_. Assuming it's installed, just run this from the command-line:
 
 .. sourcecode:: none
 
     # pip install SQLAlchemy
 
 This command will download the latest version of SQLAlchemy from the `Python
-Cheese Shop <http://pypi.python.org/pypi/SQLAlchemy>`_ and install it to your
-system.
+Cheese Shop <http://pypi.python.org/pypi/SQLAlchemy>`_ and install it to your system.
+
+Installing using setup.py
+----------------------------------
 
 Otherwise, you can install from the distribution using the ``setup.py`` script:
 
 
     # python setup.py install
 
+Installing the C Extensions
+----------------------------------
+
+SQLAlchemy includes C extensions which provide an extra speed boost for dealing with result sets.   These extensions build automatically when the build or install commands of setup.py are invoked.  If the C extensions cannot be built, the setup process will output a warning message.
+
+To disable building the C extensions, pass the flag ``--with-no-cextensions`` to the ``setup.py`` script.
+
+Installing on Python 3
+----------------------------------
+
+SQLAlchemy ships as Python 2 code.   For Python 3 usage, the ``setup.py`` script will invoke the Python ``2to3`` tool on the build, plugging in an extra "preprocessor" as well.   Using the Python 3 interpreter with ``setup.py`` or a Python 3 version of easy_install or pip is all that's needed.
+
 Installing a Database API
-==========================
+----------------------------------
 
 SQLAlchemy is designed to operate with a `DB-API <http://www.python.org/doc/peps/pep-0249/>`_ implementation built for a particular database, and includes support for the most popular databases.  The current list is at :ref:`supported_dbapis`.
 
 Checking the Installed SQLAlchemy Version
-=========================================
+------------------------------------------
 
 This documentation covers SQLAlchemy version 0.7.  If you're working on a system that already has SQLAlchemy installed, check the version from your Python prompt like this:
 
      >>> sqlalchemy.__version__ # doctest: +SKIP
      0.7.0
 
+.. _migration:
+
 0.6 to 0.7 Migration
 =====================
 

File doc/build/static/docs.css

     padding:20px;
 }
 
-#pagecontrol {
-    float:right;
+
+#navbanner {
 }
 
-.topnav
-{
+#pagecontrol {
+  float:right;
+  width:300px;
+}
+
+#pagecontrol ul {
+  padding:0;
+  margin:0;
+}
+#pagecontrol li {
+    font-size:.9em;
+    list-style-type:none;
+}
+
+.topnav {
 	background-color: #fbfbee;
 	border: solid 1px #ccc;
 	padding:10px;
 	margin:10px 0px 10px 0px;
+	display:block;
 }
 
 .document {
 }
 
 .topnav h2 {
-    margin:26px 4px 0px 5px;
+    margin:8px 4px 0px 5px;
     font-family:arial,helvetica,sans-serif;
     font-size:1.6em;
     font-weight:normal;
     padding-top:10px;
 }
 
+.section ul {
+    padding: 0 0 0 25px;
+}
+
 .section {
     line-height: 1.5em;
-    padding:8px 10px 20px 10px;
+    padding:0px 10px 20px 10px;
     margin:10px 0px 0px;
 }
 
     margin:0px 0px 0px 20px;
 }
 
+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-orm {
+  float:left;
+  width:48%;
+}
+
+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;
+}
+
+
 th.field-name {
     text-align:right;
 }
 
+
 div.note, div.warning, p.deprecated  {
     background-color:#EEFFEF;
 }

File doc/build/templates/layout.mako

 
         <div class="topnav">
             <div id="pagecontrol">
-                <a href="${pathto('genindex')}">Index</a>
+                <ul>
+                % if prevtopic:
+                    <li>Prev:
+                    <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
+                    </li>
+                % endif
+                % if nexttopic:
+                    <li>Next:
+                    <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
+                    </li>
+                % endif
 
-                % if sourcename:
-                <div class="sourcelink">(<a href="${pathto('_sources/' + sourcename, True)|h}">${_('view source')})</div>
-                % endif
+                <li>
+                    <a href="${pathto('contents')}">Table of Contents</a> |
+                    <a href="${pathto('genindex')}">Index</a>
+                    % if sourcename:
+                    | <a href="${pathto('_sources/' + sourcename, True)|h}">${_('view source')}
+                    % endif
+                </li>
+                </ul>
             </div>
-
-            <div class="navbanner">
-                <a class="totoc" href="${pathto(master_doc)}">Table of Contents</a>
+            <div id="navbanner">
+                <a class="totoc" href="${pathto('index')}">${docstitle|h}</a>
                 % if parents:
                     % for parent in parents:
                         » <a href="${parent['link']|h}" title="${parent['title']}">${parent['title']}</a>
                     % endfor
                 % endif
-                % if current_page_name != master_doc:
+                % if current_page_name != 'index':
                 » ${self.show_title()} 
                 % endif
 
-                ${prevnext()}
                 <h2>
                     ${self.show_title()} 
                 </h2>
-            </div>
-            % if display_toc and not current_page_name.startswith('index'):
+            % if display_toc and \
+                    not current_page_name.startswith('index') and \
+                    not current_page_name.startswith('contents'):
                 ${toc}
             % endif
+            </div>
             <div class="clearboth"></div>
         </div>
 
 
         <%def name="footer()">
             <div class="bottomnav">
-                ${prevnext()}
+                % if prevtopic:
+                    Previous:
+                    <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
+                % endif
+                % if nexttopic:
+                    Next:
+                    <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
+                % endif
                 <div class="doc_copyright">
                 % if hasdoc('copyright'):
                     &copy; <a href="${pathto('copyright')}">Copyright</a> ${copyright|h}.
         </%def>
         ${self.footer()}
 
-<%def name="prevnext()">
-<div class="prevnext">
-    % if prevtopic:
-        Previous:
-        <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
-    % endif
-    % if nexttopic:
-        Next:
-        <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
-    % endif
-</div>
-</%def>
-
 <%def name="show_title()">
 % if title:
     ${title}