docs: merge auto generated and hand writen docs

carlosmn · Jan 19, 2013 · 181c6ed · 181c6ed
1 parent c1a48d5
commit 181c6ed
Show file tree

Hide file tree

Showing 13 changed files with 146 additions and 82 deletions.
diff --git a/docs/autodoc.rst b/docs/autodoc.rst
diff --git a/docs/config.rst b/docs/config.rst
@@ -0,0 +1,8 @@
+**********************************************************************
+Configuration file
+**********************************************************************
+
+.. autoclass:: pygit2.Config
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/diff.rst b/docs/diff.rst
@@ -0,0 +1,26 @@
+**********************************************************************
+Diff
+**********************************************************************
+
+
+A diff shows the changes between trees, an index or the working dir::
+
+    # Diff two trees
+    >>> t0 = repo.head.tree
+    >>> t1 = repo.head.parents[0].tree
+    >>> diff = t1.diff(t0)
+    >>> diff
+
+    # Diff a tree with the index
+    >>> tree = repo.head.tree
+    >>> diff = tree.diff(repo.index)
+
+    # Diff a tree with the current working dir
+    >>> tree = repo.head.tree
+    >>> diff = tree.diff()
+
+The interface for a diff::
+
+    Diff.changes          -- Dict of 'files' and 'hunks' for every change
+    Diff.patch            -- a patch for every changeset
+    Diff.merge            -- Merge two Diffs
diff --git a/docs/errors.rst b/docs/errors.rst
@@ -0,0 +1,8 @@
+**********************************************************************
+Errors
+**********************************************************************
+
+.. autoexception:: pygit2.GitError
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/index-file.rst b/docs/index-file.rst
@@ -19,3 +19,17 @@ Index write::
     >>> index.add('path/to/file')          # git add
     >>> del index['path/to/file']          # git rm
     >>> index.write()                      # don't forget to save the changes
+
+
+
+.. Autogenerated
+
+.. autoclass:: pygit2.Index
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+.. autoclass:: pygit2.IndexEntry
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/index.rst b/docs/index.rst
@@ -18,28 +18,35 @@ Pygit2 links:
 - http://www.pygit2.org/ -- Documentation
 - http://pypi.python.org/pypi/pygit2 -- Download
 
-Topics:
-
+Start:
 
 .. toctree::
    :maxdepth: 2
 
    install
-   autodoc
 
 Usage guide:
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    repository
    objects
    references
    revparse
    log
+   diff
    index-file
    status
+   config
+   errors
+
+More:
+
+.. toctree::
+   :maxdepth: 1
 
+   utils
 
 
 Indices and tables

diff --git a/docs/objects.rst b/docs/objects.rst
@@ -33,30 +33,24 @@ The API of pygit2 accepts both the raw object id and its hexadecimal
 representation, the difference is done based on its type (a byte or a text
 string).
 
-This is the common interface for all Git objects::
+Objects can not be modified once they have been created.
 
-    Object.type       -- one of the GIT_OBJ_COMMIT, GIT_OBJ_TREE,
-                         GIT_OBJ_BLOB or GIT_OBJ_TAG constants
-    Object.oid        -- the object id, a byte string 20 bytes long
-    Object.hex        -- hexadecimal representation of the object id, a text
-                         string 40 chars long
-    Object.read_raw() -- returns the byte string with the raw contents of the
-                         of the object
+This is the common interface for all Git objects:
 
-Objects can not be modified once they have been created.
+.. autoclass:: pygit2.Object
+   :members: type, oid, hex, read_raw
 
 
 Commits
 -----------------
 
 A commit is a snapshot of the working dir with meta informations like author,
-committer and others.::
+committer and others.
 
-    Commit.author    -- the author of the commit
-    Commit.committer -- the committer of the commit
-    Commit.message   -- the message, a text string
-    Commit.tree      -- the tree object attached to the commit
-    Commit.parents   -- the list of parent commits
+.. autoclass:: pygit2.Commit
+   :members: author, committer, message, message_encoding, tree, parents,
+             commit_time, commit_time_offset
+   :show-inheritance:
 
 
 Signatures
@@ -68,12 +62,8 @@ objects::
     >>> commit.author
     <pygit2.Signature object at 0x7f75e9b1f5f8>
 
-This is their interface::
-
-    Signature.name   -- person's name
-    Signature.email  -- person's email address
-    Signature.time   -- unix time
-    Signature.offset -- offset from utc in minutes
+.. autoclass:: pygit2.Signature
+   :members: name, email, time, offset
 
 
 Creating commits
@@ -137,30 +127,15 @@ This is the interface of a tree entry::
     TreeEntry.to_object() -- returns the git object (equivalent to repo[entry.oid])
 
 
-Diff
------------------
-
-A diff shows the changes between trees, an index or the working dir::
-
-    # Diff two trees
-    >>> t0 = repo.head.tree
-    >>> t1 = repo.head.parents[0].tree
-    >>> diff = t1.diff(t0)
-    >>> diff
-
-    # Diff a tree with the index
-    >>> tree = repo.head.tree
-    >>> diff = tree.diff(repo.index)
+.. autoclass:: pygit2.Tree
+   :members:
+   :show-inheritance:
+   :undoc-members:
 
-    # Diff a tree with the current working dir
-    >>> tree = repo.head.tree
-    >>> diff = tree.diff()
-
-The interface for a diff::
-
-    Diff.changes          -- Dict of 'files' and 'hunks' for every change
-    Diff.patch            -- a patch for every changeset
-    Diff.merge            -- Merge two Diffs
+.. autoclass:: pygit2.TreeEntry
+   :members:
+   :show-inheritance:
+   :undoc-members:
 
 
 Blobs
@@ -174,7 +149,20 @@ A blob is equivalent to a file in a file system.::
 
     Blob.data -- the contents of the blob, a byte string
 
+
+.. autoclass:: pygit2.Blob
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+
 Tags
 -----------------
 
 A tag is a static label for a commit. See references for more information.
+
+
+.. autoclass:: pygit2.Tag
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/references.rst b/docs/references.rst
@@ -20,3 +20,11 @@ The interface for RefLogEntry::
     RefLogEntry.message   -- the message of the RefLogEntry
     RefLogEntry.oid_old   -- oid of old reference
     RefLogEntry.oid_new   -- oid of new reference
+
+
+.. Autogenerated
+
+.. autoclass:: pygit2.Reference
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/repository.rst b/docs/repository.rst
@@ -2,23 +2,21 @@
 The repository
 **********************************************************************
 
-
 Everything starts by opening an existing repository::
 
     >>> from pygit2 import Repository
     >>> repo = Repository('pygit2/.git')
 
-
 Or by creating a new one::
 
     >>> from pygit2 import init_repository
     >>> bare = False
     >>> repo = init_repository('test', bare)
 
 
+.. autofunction:: pygit2.init_repository
 
-These are the basic attributes of a repository::
+.. autofunction:: pygit2.discover_repository
 
-    Repository.path    -- path to the Git repository
-    Repository.workdir -- path to the working directory, None in the case of
-                          a bare repo
+.. autoclass:: pygit2.Repository
+   :members:
diff --git a/docs/utils.rst b/docs/utils.rst
@@ -0,0 +1,8 @@
+**********************************************************************
+Utilities
+**********************************************************************
+
+.. automodule:: pygit2.utils
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/src/pygit2/commit.c b/src/pygit2/commit.c
@@ -156,17 +156,22 @@ Commit_get_parents(Commit *commit)
 PyGetSetDef Commit_getseters[] = {
     {"message_encoding", (getter)Commit_get_message_encoding, NULL,
      "message encoding", NULL},
-    {"message", (getter)Commit_get_message, NULL, "message", NULL},
-    {"_message", (getter)Commit_get_raw_message, NULL, "message (bytes)", NULL},
+    {"message", (getter)Commit_get_message, NULL,
+     "The commit message, a text string.", NULL},
+    {"_message", (getter)Commit_get_raw_message, NULL, "message (bytes)",
+     NULL},
     {"commit_time", (getter)Commit_get_commit_time, NULL, "commit time",
      NULL},
     {"commit_time_offset", (getter)Commit_get_commit_time_offset, NULL,
      "commit time offset", NULL},
-    {"committer", (getter)Commit_get_committer, NULL, "committer", NULL},
-    {"author", (getter)Commit_get_author, NULL, "author", NULL},
-    {"tree", (getter)Commit_get_tree, NULL, "tree object", NULL},
-    {"parents", (getter)Commit_get_parents, NULL, "parents of this commit",
-      NULL},
+    {"committer", (getter)Commit_get_committer, NULL,
+     "The committer of the commit.", NULL},
+    {"author", (getter)Commit_get_author, NULL,
+     "The author of the commit.", NULL},
+    {"tree", (getter)Commit_get_tree, NULL,
+     "The tree object attached to the commit.", NULL},
+    {"parents", (getter)Commit_get_parents, NULL,
+     "The list of parent commits.", NULL},
     {NULL}
 };
 

diff --git a/src/pygit2/object.c b/src/pygit2/object.c
@@ -99,15 +99,22 @@ Object_read_raw(Object *self)
 }
 
 PyGetSetDef Object_getseters[] = {
-    {"oid", (getter)Object_get_oid, NULL, "object id", NULL},
-    {"hex", (getter)Object_get_hex, NULL, "hex oid", NULL},
-    {"type", (getter)Object_get_type, NULL, "type number", NULL},
+    {"oid", (getter)Object_get_oid, NULL,
+     "The object id, a byte string 20 bytes long.", NULL},
+    {"hex", (getter)Object_get_hex, NULL,
+     "Hexadecimal representation of the object id, a text string 40 chars "
+     "long.",
+     NULL},
+    {"type", (getter)Object_get_type, NULL,
+     "One of the GIT_OBJ_COMMIT, GIT_OBJ_TREE, GIT_OBJ_BLOB or "
+     "GIT_OBJ_TAG constants.",
+     NULL},
     {NULL}
 };
 
 PyMethodDef Object_methods[] = {
     {"read_raw", (PyCFunction)Object_read_raw, METH_NOARGS,
-     "Read the raw contents of the object from the repo."},
+     "Returns the byte string with the raw contents of the of the object."},
     {NULL}
 };
 

diff --git a/src/pygit2/signature.c b/src/pygit2/signature.c
@@ -143,9 +143,10 @@ PyGetSetDef Signature_getseters[] = {
     {"_name", (getter)Signature_get_raw_name, NULL, "Name (bytes)", NULL},
     {"_email", (getter)Signature_get_raw_email, NULL, "Email (bytes)", NULL},
     {"name", (getter)Signature_get_name, NULL, "Name", NULL},
-    {"email", (getter)Signature_get_email, NULL, "Email", NULL},
-    {"time", (getter)Signature_get_time, NULL, "Time", NULL},
-    {"offset", (getter)Signature_get_offset, NULL, "Offset", NULL},
+    {"email", (getter)Signature_get_email, NULL, "Email address", NULL},
+    {"time", (getter)Signature_get_time, NULL, "Unix time", NULL},
+    {"offset", (getter)Signature_get_offset, NULL,
+     "Offset from UTC in minutes", NULL},
     {NULL}
 };