Add documentation for custom refdb/odb backends

Author: ddevault

docs/backends.rst

@@ -2,7 +2,41 @@
 Backends
 **********************************************************************
 
-There is some support for custom backends, but undocumented. See
-`<https://github.com/libgit2/pygit2/pull/690/commits>`_
+The use of custom backends for the git object database (odb) and reference
+database (refdb) are supported by pygit2.
 
-Documentation contributions are very welcome.
+.. contents:: Contents
+   :local:
+
+The OdbBackend class
+===================================
+
+The OdbBackend class is subclassable and can be used to build a custom object
+database.
+
+.. autoclass:: pygit2.OdbBackend
+   :members:
+
+Built-in OdbBackend implementations
+===================================
+
+.. autoclass:: pygit2.OdbBackendLoose
+   :members:
+
+.. autoclass:: pygit2.OdbBackendPack
+   :members:
+
+The RefdbBackend class
+===================================
+
+The RefdbBackend class is subclassable and can be used to build a custom
+reference database.
+
+.. autoclass:: pygit2.RefdbBackend
+   :members:
+
+Built-in RefdbBackend implementations
+=====================================
+
+.. autoclass:: pygit2.RefdbFsBackend
+   :members:

docs/repository.rst

@@ -56,10 +56,14 @@ Below there are some general attributes and methods:
    :members: ahead_behind, apply, create_reference, default_signature,
              descendant_of, describe, free, is_bare, is_empty, odb, path,
              path_is_ignored, reset, revert_commit, state_cleanup, workdir,
-             write_archive
+             write_archive, set_odb, set_refdb
 
    The Repository constructor only takes one argument, the path of the
-   repository to open.
+   repository to open. Alternatively, constructing a repository with no
+   arguments will create a repository with no backends. You can use this path
+   to create repositories with custom backends. Note that most operations on
+   the repository are considered invalid and may lead to undefined behavior if
+   attempted before providing an odb and refdb via set_odb and set_refdb.
 
    Example::
 
@@ -73,5 +77,8 @@ The Odb class
 .. autoclass:: pygit2.Odb
    :members:
 
-.. autoclass:: pygit2.OdbBackend
+The Refdb class
+===================================
+
+.. autoclass:: pygit2.Refdb
    :members:

src/odb_backend.c

@@ -772,8 +772,8 @@ PyTypeObject OdbBackendPackType = {
 };
 
 PyDoc_STRVAR(OdbBackendLoose__doc__,
-        "OdbBackendLoose(objects_dir, compression_level,\n"
-        "    do_fsync, dir_mode=0, file_mode=0)\n"
+        "OdbBackendLoose(objects_dir, compression_level,"
+        " do_fsync, dir_mode=0, file_mode=0)\n"
         "\n"
         "Object database backend for loose objects.\n"
         "\n"

src/refdb_backend.c

@@ -582,8 +582,8 @@ RefdbBackend_lookup(RefdbBackend *self, PyObject *py_str)
 }
 
 PyDoc_STRVAR(RefdbBackend_write__doc__,
-    "write(ref: Reference, force: bool, who: Signature, message: str, \n"
-    "   old: oid, old_target: str)\n"
+    "write(ref: Reference, force: bool, who: Signature, message: str, "
+    "old: oid, old_target: str)\n"
     "\n"
     "Writes a new reference to the reference database.");
 // TODO: Better docs? libgit2 is scant on documentation for this, too.