From: Mike Bayer Date: Fri, 15 Apr 2011 00:50:52 +0000 (-0400) Subject: - add a new "documentation overview" page. rip off a project widely known X-Git-Tag: rel_0_7b4~14 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3f06806cff8c9f064e5b5415259907b82674687a;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - add a new "documentation overview" page. rip off a project widely known to start with "Dj". --- diff --git a/doc/build/conf.py b/doc/build/conf.py index 14820b53fb..6c9e39aff9 100644 --- a/doc/build/conf.py +++ b/doc/build/conf.py @@ -49,7 +49,7 @@ template_bridge = "builder.builders.MakoBridge" #source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'index' +master_doc = 'contents' # General information about the project. project = u'SQLAlchemy' diff --git a/doc/build/contents.rst b/doc/build/contents.rst new file mode 100644 index 0000000000..dcd9171de8 --- /dev/null +++ b/doc/build/contents.rst @@ -0,0 +1,21 @@ +.. _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` diff --git a/doc/build/core/schema.rst b/doc/build/core/schema.rst index d7fa8ad24b..8525f3bb5a 100644 --- a/doc/build/core/schema.rst +++ b/doc/build/core/schema.rst @@ -6,6 +6,9 @@ Schema Definition Language .. module:: sqlalchemy.schema + +.. _metadata_describing: + Describing Databases with MetaData ================================== @@ -532,6 +535,9 @@ database is also available. This is known as the "Inspector":: :undoc-members: :show-inheritance: + +.. _metadata_defaults: + Column Insert/Update Defaults ============================== @@ -841,6 +847,7 @@ Defining Constraints and Indexes ================================= .. _metadata_foreignkeys: +.. _metadata_constraints: Defining Foreign Keys --------------------- @@ -1166,6 +1173,8 @@ The :class:`~sqlalchemy.schema.Index` object also supports its own ``create()`` .. autoclass:: Index :show-inheritance: +.. _metadata_ddl: + Customizing DDL =============== diff --git a/doc/build/core/types.rst b/doc/build/core/types.rst index 04b9b37b54..16a34c0368 100644 --- a/doc/build/core/types.rst +++ b/doc/build/core/types.rst @@ -28,6 +28,8 @@ Functions that accept a type (such as :func:`~sqlalchemy.Column`) will typically accept a type class or instance; ``Integer`` is equivalent to ``Integer()`` with no construction arguments in this case. +.. _types_generic: + Generic Types ------------- @@ -111,6 +113,8 @@ Standard Types`_ and the other sections of this chapter. :show-inheritance: :members: +.. _types_sqlstandard: + SQL Standard Types ------------------ @@ -184,6 +188,7 @@ on all databases. .. autoclass:: VARCHAR :show-inheritance: +.. _types_vendor: Vendor-Specific Types --------------------- @@ -239,6 +244,8 @@ such as `collation` and `charset`:: Column('col2', TEXT(charset='latin1')) ) +.. _types_custom: + Custom Types ------------ @@ -412,6 +419,8 @@ for defining entirely new database types: :inherited-members: :show-inheritance: +.. _types_api: + Base Type API -------------- diff --git a/doc/build/dialects/index.rst b/doc/build/dialects/index.rst index 7d745d4cb0..9865d37ec4 100644 --- a/doc/build/dialects/index.rst +++ b/doc/build/dialects/index.rst @@ -29,3 +29,4 @@ should be consulted to check for current support level. sybase + diff --git a/doc/build/index.rst b/doc/build/index.rst index e6442efd0c..e25a982372 100644 --- a/doc/build/index.rst +++ b/doc/build/index.rst @@ -1,16 +1,119 @@ -Table of Contents -================= +.. _index_toplevel: -.. toctree:: - :maxdepth: 2 +======================== +SQLAlchemy Documentation +======================== - intro - orm/index - core/index - dialects/index +Getting Started +=============== + +A high level view and getting set up. + +:ref:`Overview ` | +:ref:`Installation Guide ` | +:ref:`Migration from 0.6 ` + +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 ` | + :doc:`Relationship Configuration ` | + :doc:`Inheritance Mapping ` | + :doc:`Advanced Collection Configuration ` + +* **Configuration Extensions:** + :doc:`Declarative Extension ` | + :doc:`Association Proxy ` | + :doc:`Hybrid Attrbutes ` | + :doc:`Mutable Scalars ` | + :doc:`Ordered List ` + +* **ORM Usage:** + :doc:`Session Usage and Guidelines ` | + :doc:`Query API reference ` | + :doc:`Relationship Loading Techniques ` + +* **Extending the ORM:** + :doc:`ORM Event Interfaces ` | + :doc:`Internals API ` + +* **Other:** + :doc:`Introduction to Examples ` | + :doc:`Deprecated Event Interfaces ` | + :doc:`ORM Exceptions ` | + :doc:`Horizontal Sharding ` | + :doc:`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 ` + +* **Engines, Connections, Pools:** + :doc:`Engine Configuration ` | + :doc:`Connections, Transactions ` | + :doc:`Connection Pooling ` + +* **Schema Definition:** + :ref:`Tables and Columns ` | + :ref:`Database Introspection (Reflection) ` | + :ref:`Insert/Update Defaults ` | + :ref:`Constraints and Indexes ` | + :ref:`Using Data Definition Language (DDL) ` + +* **Datatypes:** + :ref:`Overview ` | + :ref:`Generic Types ` | + :ref:`SQL Standard Types ` | + :ref:`Vendor Specific Types ` | + :ref:`Building Custom Types ` | + :ref:`API ` + +* **Extending the Core:** + :doc:`SQLAlchemy Events ` | + :doc:`Core Event Interfaces ` | + :doc:`Creating Custom SQL Constructs ` | + :doc:`Internals API ` + +* **Other:** + :doc:`Serializing Expressions ` | + :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` -Indices and tables ------------------- -* :ref:`genindex` -* :ref:`search` diff --git a/doc/build/intro.rst b/doc/build/intro.rst index d3409cec38..0fa49ac0a9 100644 --- a/doc/build/intro.rst +++ b/doc/build/intro.rst @@ -1,12 +1,13 @@ .. _overview_toplevel: -======================= -Overview / Installation -======================= - +======== Overview ======== +.. _overview: + +Overview +======== The SQLAlchemy SQL Toolkit and Object Relational Mapper is a comprehensive set of tools for working with @@ -25,6 +26,8 @@ Expression language remains part of the public facing API as it is used within object-relational configurations and queries. +.. _doc_overview: + Documentation Overview ====================== @@ -37,16 +40,15 @@ as well as management of Python objects, proceed to this tutorial. 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 @@ -60,13 +62,19 @@ There is also a wide variety of examples involving both core SQLAlchemy constructs as well as the ORM on the wiki. See ``_. -Installing SQLAlchemy -====================== +.. _installation: + +Installation Guide +================== + +SQLAlchemy builds using the standard `Python Distutils `_ approach. + +Installing with setuptools or pip +---------------------------------- Installing SQLAlchemy from scratch is most easily achieved with `setuptools `_, or alternatively -`pip `_. Assuming it's installed, just run -this from the command-line: +`pip `_. Assuming it's installed, just run this from the command-line: .. sourcecode:: none @@ -79,8 +87,10 @@ Or with pip: # pip install SQLAlchemy This command will download the latest version of SQLAlchemy from the `Python -Cheese Shop `_ and install it to your -system. +Cheese Shop `_ and install it to your system. + +Installing using setup.py +---------------------------------- Otherwise, you can install from the distribution using the ``setup.py`` script: @@ -88,13 +98,25 @@ 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 `_ 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: @@ -104,6 +126,8 @@ This documentation covers SQLAlchemy version 0.7. If you're working on a system >>> sqlalchemy.__version__ # doctest: +SKIP 0.7.0 +.. _migration: + 0.6 to 0.7 Migration ===================== diff --git a/doc/build/static/docs.css b/doc/build/static/docs.css index 697837e947..9518b9013f 100644 --- a/doc/build/static/docs.css +++ b/doc/build/static/docs.css @@ -43,16 +43,30 @@ strong a { padding:20px; } + +#navbanner { +} + #pagecontrol { - float:right; + float:right; + width:300px; } -.topnav -{ +#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 { @@ -90,7 +104,7 @@ h1 { } .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; @@ -133,9 +147,13 @@ li.toctree-l1 ul li li 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; } @@ -152,10 +170,50 @@ li.toctree-l1 ul li li 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; } diff --git a/doc/build/templates/layout.mako b/doc/build/templates/layout.mako index 879818efa7..1bfa5c9851 100644 --- a/doc/build/templates/layout.mako +++ b/doc/build/templates/layout.mako @@ -57,32 +57,47 @@
- Index - - % if sourcename: -
(${_('view source')})
+
-
- Table of Contents +
  • + Table of Contents | + Index + % if sourcename: + | ${_('view source')} + % endif +
    • + +
    + - % 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 +
    @@ -94,7 +109,14 @@ <%def name="footer()">
    - ${prevnext()} + % if prevtopic: + Previous: + ${prevtopic['title']} + % endif + % if nexttopic: + Next: + ${nexttopic['title']} + % endif
    % if hasdoc('copyright'): © Copyright ${copyright|h}. @@ -109,19 +131,6 @@ ${self.footer()} -<%def name="prevnext()"> -
    - % if prevtopic: - Previous: - ${prevtopic['title']} - % endif - % if nexttopic: - Next: - ${nexttopic['title']} - % endif -
    - - <%def name="show_title()"> % if title: ${title}