Merge lp:~muffinresearch/u1db/docs-tweaks into lp:u1db

[Stuart Colville]

Make conditional theme available for u1db site and fix markup output.

* Make theming conditional - please check docs build ok sans those paths.
* Add current year to date string in docs
* Fix some output issues in .rst files which caused markup to have unnecessary blockquotes.

[Eric Casteleijn (thisfred)]

changes as well as resulting html look good, +1

review: Approve

=== modified file 'html-docs/conf.py'
--- html-docs/conf.py	2011-12-20 13:31:32 +0000
+++ html-docs/conf.py	2012-09-18 16:33:23 +0000
@@ -11,7 +11,9 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
+import datetime
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -25,7 +27,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage', 
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage',
     'sphinx.ext.viewcode']
 
 # Add any paths that contain templates here, relative to this directory.
@@ -41,8 +43,9 @@
 master_doc = 'index'
 
 # General information about the project.
+now = datetime.datetime.now()
 project = u'u1db'
-copyright = u'2011, Ubuntu One team'
+copyright = u'2011-%s, Ubuntu One team' % now.year
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -83,7 +86,7 @@
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = 'colorful'
 
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
@@ -93,7 +96,11 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+
+if os.path.exists("../../../themes/u1db"):
+    html_theme = "u1db"
+else:
+    html_theme = 'default'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -101,7 +108,7 @@
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+html_theme_path = ["../../../themes/"]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -122,7 +129,11 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+
+if os.path.exists("../../../static"):
+    html_static_path = ['../../../static']
+else:
+    html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

=== modified file 'html-docs/conflicts.rst'
--- html-docs/conflicts.rst	2012-08-22 17:03:24 +0000
+++ html-docs/conflicts.rst	2012-09-18 16:33:23 +0000
@@ -86,50 +86,50 @@
 
 Synchronisation between two u1db replicas consists of the following steps:
 
-    1. The source replica asks the target replica for the information it has
-       stored about the last time these two replicas were synchronised (if
-       ever).
-
-    2. The source replica validates that its information regarding the last
-       synchronisation is consistent with the target's information, and
-       raises an error if not. (This could happen for instance if one of the
-       replicas was lost and restored from backup, or if a user inadvertently
-       tries to synchronise a copied database.)
-
-    3. The source replica generates a list of changes since the last change the
-       target replica knows of.
-
-    4. The source replica checks what the last change is it knows about on the
-       target replica.
-
-    5. If there have been no changes on either replica that the other side has
-       not seen, the synchronisation stops here.
-
-    6. The source replica sends the changed documents to the target, along with
-       what the latest change is that it knows about on the target replica.
-
-    7. The target processes the changed documents, and records the source
-       replica's latest change.
-
-    8. The target responds with the documents that have changes that the source
-       does not yet know about.
-
-    9. The source processes the changed documents, and records the target
-       replica's latest change.
-
-    10. If the source has seen no changes unrelated to the synchronisation
-        during this whole process, it now sends the target what its latest
-        change is, so that the next synchronisation does not have to consider
-        changes that were the result of this one.
+1. The source replica asks the target replica for the information it has
+   stored about the last time these two replicas were synchronised (if
+   ever).
+
+2. The source replica validates that its information regarding the last
+   synchronisation is consistent with the target's information, and
+   raises an error if not. (This could happen for instance if one of the
+   replicas was lost and restored from backup, or if a user inadvertently
+   tries to synchronise a copied database.)
+
+3. The source replica generates a list of changes since the last change the
+   target replica knows of.
+
+4. The source replica checks what the last change is it knows about on the
+   target replica.
+
+5. If there have been no changes on either replica that the other side has
+   not seen, the synchronisation stops here.
+
+6. The source replica sends the changed documents to the target, along with
+   what the latest change is that it knows about on the target replica.
+
+7. The target processes the changed documents, and records the source
+   replica's latest change.
+
+8. The target responds with the documents that have changes that the source
+   does not yet know about.
+
+9. The source processes the changed documents, and records the target
+   replica's latest change.
+
+10. If the source has seen no changes unrelated to the synchronisation
+    during this whole process, it now sends the target what its latest
+    change is, so that the next synchronisation does not have to consider
+    changes that were the result of this one.
 
 The synchronisation information stored by the replica for each other replica it
 has ever synchronised with consists of:
 
-    * The replica id of the other replica. (Which should be globally unique
-      identifier to distinguish database replicas from one another.)
-    * The last known generation and transaction id of the other replica.
-    * The generation and transaction id of *this* replica at the time of the
-      most recent succesfully completed synchronisation with the other replica.
+* The replica id of the other replica. (Which should be globally unique
+  identifier to distinguish database replicas from one another.)
+* The last known generation and transaction id of the other replica.
+* The generation and transaction id of *this* replica at the time of the
+  most recent succesfully completed synchronisation with the other replica.
 
 Any change to any document in a database constitutes a transaction. Each
 transaction increases the database generation by 1, and u1db implementations
@@ -151,93 +151,94 @@
 Synchronisation over HTTP is tuned to minimize the number of request/response
 round trips. The anatomy of a full synchronisation over HTTP is as follows:
 
-    1. The application wishing to synchronise sends the following GET request
-       to the server::
-
-            GET /thedb/sync-from/my_replica_uid
-
-       Where ``thedb`` is the name of the database to be synchronised, and
-       ``my_replica_uid`` is the replica id of the application's (i.e. the
-       local, or synchronisation source) database.
-
-    2. The target responds with a JSON document that looks like this::
-
-            {
-                "target_replica_uid": "other_replica_uid",
-                "target_replica_generation": 12,
-                "target_replica_transaction_id": "T-sdkfj92292j",
-                "source_replica_uid": "my_replica_uid",
-                "source_replica_generation": 23,
-                "source_transaction_id": "T-39299sdsfla8"
-            }
-
-       With all the information it has stored for the most recent
-       synchronisation between itself and this particular source replica. In
-       this case it tells us that the synchronisation target believes that when
-       it and the source were last synchronised, the target was at generation
-       12 and the source at generation 23.
-
-    3. If source and target agree on the above information, the source now
-       starts a streaming POST request to the same URL::
-
-            POST /thedb/sync-from/my_replica_uid
-
-       The request is of MIME type ``application/x-u1db-sync-stream``, which is
-       a subset of JSON. The format is a JSON array with a JSON object on each
-       line, followed by a comma and a carriage return and a newline, like
-       this::
-
-            [\r\n
-            {json_object},\r\n
-            ...
-            ]
-
-       The first object contains the following information::
-
-            {"last_known_generation": 12, "last_known_trans_id": "T-39299sdsfla8"},\r\n
-
-       and then for each document that it has changes for that are more recent
-       than generation 23, ordered by generation in ascending order, it sends,
-       on a single line, followed by a comma and a newline character, the
-       following JSON object::
-
-            {"id": "mydocid", "rev": "my_replica_uid:4", "content": "{}", "generation": 48, "trans_id": "T-88djlahhhd"},\r\n
-
+1. The application wishing to synchronise sends the following GET request
+   to the server::
+
+        GET /thedb/sync-from/my_replica_uid
+
+   Where ``thedb`` is the name of the database to be synchronised, and
+   ``my_replica_uid`` is the replica id of the application's (i.e. the
+   local, or synchronisation source) database.
+
+2. The target responds with a JSON document that looks like this::
+
+        {
+            "target_replica_uid": "other_replica_uid",
+            "target_replica_generation": 12,
+            "target_replica_transaction_id": "T-sdkfj92292j",
+            "source_replica_uid": "my_replica_uid",
+            "source_replica_generation": 23,
+            "source_transaction_id": "T-39299sdsfla8"
+        }
+
+   With all the information it has stored for the most recent
+   synchronisation between itself and this particular source replica. In
+   this case it tells us that the synchronisation target believes that when
+   it and the source were last synchronised, the target was at generation
+   12 and the source at generation 23.
+
+3. If source and target agree on the above information, the source now
+   starts a streaming POST request to the same URL::
+
+        POST /thedb/sync-from/my_replica_uid
+
+   The request is of MIME type ``application/x-u1db-sync-stream``, which is
+   a subset of JSON. The format is a JSON array with a JSON object on each
+   line, followed by a comma and a carriage return and a newline, like
+   this::
+
+        [\r\n
+        {json_object},\r\n
+        ...
+        ]
+
+   The first object contains the following information::
+
+        {"last_known_generation": 12, "last_known_trans_id": "T-39299sdsfla8"},\r\n
+
+   and then for each document that it has changes for that are more recent
+   than generation 23, ordered by generation in ascending order, it sends,
+   on a single line, followed by a comma and a newline character, the
+   following JSON object::
+
+        {"id": "mydocid", "rev": "my_replica_uid:4", "content": "{}", "generation": 48, "trans_id": "T-88djlahhhd"},\r\n
+
+   .. note::
        Note that content contains a JSON encoded representation of the
        document's content (which in this case is empty).
 
-       The server reads and processes these lines one by one. Note that each
-       such JSON document includes the generation and transaction id of the
-       change. This means that when the synchronisation is ever interrupted,
-       the source can resume by starting at the last generation that was
-       successfully synchronised.
-
-    4. After it gets to the end of the request, the server responds with a
-       status 200 and starts streaming a response, also of MIME type
-       ``application/x-u1db-sync-stream``, which starts as follows::
-
-            [\r\n
-            {"new_generation": 15, "new_transaction_id": "T-999j3jjsfl"},\r\n
-
-       which tells the source what the target's new generation and transaction
-       id are, now that it processed the changes it received from the source.
-       Then it starts streaming  *its* changes since its last generation that
-       was synced (12 in this case), in exactly the same format (and order) as
-       the source did in step 3.
-
-    5. When the source has processed all the changes it received from the
-       target, *and* it detects that there have been no changes to its database
-       since the start of the synchronisation that were not a direct result
-       *of* the synchronisation, it now performs a final PUT request, to inform
-       the target of its new generation and transaction id, so that the next
-       synchronisation can start there, rather than with the generation the
-       source was at when this synchronisation started::
-
-            PUT /thedb/sync-from/my_replica_uid
-
-       With the content::
-
-            {"generation": 53, "transaction_id": "T-camcmls92"}
+   The server reads and processes these lines one by one. Note that each
+   such JSON document includes the generation and transaction id of the
+   change. This means that when the synchronisation is ever interrupted,
+   the source can resume by starting at the last generation that was
+   successfully synchronised.
+
+4. After it gets to the end of the request, the server responds with a
+   status 200 and starts streaming a response, also of MIME type
+   ``application/x-u1db-sync-stream``, which starts as follows::
+
+        [\r\n
+        {"new_generation": 15, "new_transaction_id": "T-999j3jjsfl"},\r\n
+
+   which tells the source what the target's new generation and transaction
+   id are, now that it processed the changes it received from the source.
+   Then it starts streaming  *its* changes since its last generation that
+   was synced (12 in this case), in exactly the same format (and order) as
+   the source did in step 3.
+
+5. When the source has processed all the changes it received from the
+   target, *and* it detects that there have been no changes to its database
+   since the start of the synchronisation that were not a direct result
+   *of* the synchronisation, it now performs a final PUT request, to inform
+   the target of its new generation and transaction id, so that the next
+   synchronisation can start there, rather than with the generation the
+   source was at when this synchronisation started::
+
+        PUT /thedb/sync-from/my_replica_uid
+
+   With the content::
+
+        {"generation": 53, "transaction_id": "T-camcmls92"}
 
 
 Revisions

=== modified file 'html-docs/high-level-api.rst'
--- html-docs/high-level-api.rst	2012-08-22 17:03:24 +0000
+++ html-docs/high-level-api.rst	2012-09-18 16:33:23 +0000
@@ -122,18 +122,17 @@
     >>> doc = db.get_doc(doc.doc_id, include_deleted=True)
     >>> doc.content
 
-
 Document functions
 ^^^^^^^^^^^^^^^^^^
 
- * :py:meth:`~u1db.Database.create_doc`
- * :py:meth:`~u1db.Database.create_doc_from_json`
- * :py:meth:`~u1db.Database.put_doc`
- * :py:meth:`~u1db.Database.get_doc`
- * :py:meth:`~u1db.Database.get_docs`
- * :py:meth:`~u1db.Database.get_all_docs`
- * :py:meth:`~u1db.Database.delete_doc`
- * :py:meth:`~u1db.Database.whats_changed`
+* :py:meth:`~u1db.Database.create_doc`
+* :py:meth:`~u1db.Database.create_doc_from_json`
+* :py:meth:`~u1db.Database.put_doc`
+* :py:meth:`~u1db.Database.get_doc`
+* :py:meth:`~u1db.Database.get_docs`
+* :py:meth:`~u1db.Database.get_all_docs`
+* :py:meth:`~u1db.Database.delete_doc`
+* :py:meth:`~u1db.Database.whats_changed`
 
 Querying
 --------
@@ -161,14 +160,14 @@
 an index expression of ``"firstname"`` will create an index that looks
 (conceptually) like this
 
- ====================== ========
- index expression value document
- ====================== ========
- Alan                   ah
- Jan                    jm
- John                   jb
- John                   jw
- ====================== ========
+====================== ========
+index expression value document
+====================== ========
+Alan                   ah
+Jan                    jm
+John                   jb
+John                   jw
+====================== ========
 
 and that index is created with:
 
@@ -204,11 +203,11 @@
 
 gives the index key "hello", and therefore an entry in the index of
 
- ========= ====
- Index key doc
- ========= ====
- hello     doc1
- ========= ====
+========= ====
+Index key doc
+========= ====
+hello     doc1
+========= ====
 
 **Name a list.** If an index expression names a field whose contents is a list
 of strings, the document will have multiple entries in the index, one per entry
@@ -226,13 +225,13 @@
 
 gives index entries
 
- ========= ====
- Index key doc
- ========= ====
- tag1      doc2
- tag2      doc2
- tag3      doc2
- ========= ====
+========= ====
+Index key doc
+========= ====
+tag1      doc2
+tag2      doc2
+tag3      doc2
+========= ====
 
 **Subfields of objects in a list.** If an index expression points at subfields
 of objects in a list, the document will have multiple entries in the index, one
@@ -257,12 +256,12 @@
 
 would give index entries:
 
- ========= ====
- Index key doc
- ========= ====
- 12345     doc3
- 54321     doc3
- ========= ====
+========= ====
+Index key doc
+========= ====
+12345     doc3
+54321     doc3
+========= ====
 
 **Transformation functions.** An index expression may be wrapped in any number
 of transformation functions. A function transforms the result of the contained
@@ -272,16 +271,16 @@
 
 Available transformation functions are:
 
- * ``lower(index_expression)`` - lowercase the value
- * ``split_words(index_expression)`` - split the value on whitespace; will act
-   like a list and add multiple entries to the index
- * ``number(index_expression, width)`` - takes an integer value, and turns it
-   into a string, left padded with zeroes, to make it at least as wide as
-   width; or nothing if the field type is not an integer.
- * ``bool(index_expression)`` - takes a boolean value and turns it into '0' if
-   false and '1' if true, or nothing if the field type is not boolean.
- * ``combine(index_expression1, index_expression2, ...)`` - Combine the values
-   of an arbitrary number of sub expressions into a single index.
+* ``lower(index_expression)`` - lowercase the value
+* ``split_words(index_expression)`` - split the value on whitespace; will act
+  like a list and add multiple entries to the index
+* ``number(index_expression, width)`` - takes an integer value, and turns it
+  into a string, left padded with zeroes, to make it at least as wide as
+  width; or nothing if the field type is not an integer.
+* ``bool(index_expression)`` - takes a boolean value and turns it into '0' if
+  false and '1' if true, or nothing if the field type is not boolean.
+* ``combine(index_expression1, index_expression2, ...)`` - Combine the values
+  of an arbitrary number of sub expressions into a single index.
 
 So, the index expression ``splitwords(lower(field.name))`` applied to
 a document with content:
@@ -297,13 +296,13 @@
 
 gives index entries
 
- ========== ====
- Index key  doc
- ========== ====
- bruce      doc3
- david      doc3
- grobbelaar doc3
- ========== ====
+========== ====
+Index key  doc
+========== ====
+bruce      doc3
+david      doc3
+grobbelaar doc3
+========== ====
 
 
 Querying an index
@@ -336,12 +335,12 @@
 Index functions
 ^^^^^^^^^^^^^^^
 
- * :py:meth:`~u1db.Database.create_index`
- * :py:meth:`~u1db.Database.delete_index`
- * :py:meth:`~u1db.Database.get_from_index`
- * :py:meth:`~u1db.Database.get_range_from_index`
- * :py:meth:`~u1db.Database.get_index_keys`
- * :py:meth:`~u1db.Database.list_indexes`
+* :py:meth:`~u1db.Database.create_index`
+* :py:meth:`~u1db.Database.delete_index`
+* :py:meth:`~u1db.Database.get_from_index`
+* :py:meth:`~u1db.Database.get_range_from_index`
+* :py:meth:`~u1db.Database.get_index_keys`
+* :py:meth:`~u1db.Database.list_indexes`
 
 Synchronising
 -------------
@@ -377,9 +376,9 @@
 Synchronising Functions
 ^^^^^^^^^^^^^^^^^^^^^^^
 
- * :py:meth:`~u1db.Database.sync`
- * :py:meth:`~u1db.Database.get_doc_conflicts`
- * :py:meth:`~u1db.Database.resolve_doc`
+* :py:meth:`~u1db.Database.sync`
+* :py:meth:`~u1db.Database.get_doc_conflicts`
+* :py:meth:`~u1db.Database.resolve_doc`
 
 .. rubric:: footnotes
 

=== modified file 'html-docs/index.rst'
--- html-docs/index.rst	2012-08-21 16:00:44 +0000
+++ html-docs/index.rst	2012-09-18 16:33:23 +0000
@@ -39,18 +39,18 @@
 
 Choose the implementation you need and get hacking!
 
- ===================== =========== ================= ==============
- Platform(s)           Language    Back end database link
- ===================== =========== ================= ==============
- Ubuntu, Windows, OS X Python      SQLite            :ref:`reference-implementation`
- Ubuntu                Vala        SQLite            `lp:shardbridge <http://launchpad.net/shardbridge/>`_
- Ubuntu, Windows, OS X C           SQLite            part of `lp:u1db <http://launchpad.net/u1db/>`_
- Ubuntu, Windows, OS X Go          LevelDB and/or    `lp:gouda <http://launchpad.net/gouda/>`_ (in progress)
-                                   MongoDB
- Web                   JavaScript  localStorage      planned
- Android               Java        SQLite            planned
- iOS                   Objective C SQLite            planned
- ===================== =========== ================= ==============
+===================== =========== ================= ==============
+Platform(s)           Language    Back end database link
+===================== =========== ================= ==============
+Ubuntu, Windows, OS X Python      SQLite            :ref:`reference-implementation`
+Ubuntu                Vala        SQLite            `lp:shardbridge <http://launchpad.net/shardbridge/>`_
+Ubuntu, Windows, OS X C           SQLite            part of `lp:u1db <http://launchpad.net/u1db/>`_
+Ubuntu, Windows, OS X Go          LevelDB and/or    `lp:gouda <http://launchpad.net/gouda/>`_ (in progress)
+                                  MongoDB
+Web                   JavaScript  localStorage      planned
+Android               Java        SQLite            planned
+iOS                   Objective C SQLite            planned
+===================== =========== ================= ==============
 
 
 Indices and tables