diff --git a/docs/autodoc.rst b/docs/autodoc.rst deleted file mode 100644 index fee3bdf..0000000 --- a/docs/autodoc.rst +++ /dev/null @@ -1,14 +0,0 @@ -API Reference -============= - -.. Util functions -.. automodule:: pygit2.utils - :members: - :show-inheritance: - :undoc-members: - -.. c extension -.. automodule:: _pygit2 - :members: - :show-inheritance: - :undoc-members: diff --git a/docs/config.rst b/docs/config.rst new file mode 100644 index 0000000..3c15052 --- /dev/null +++ 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 new file mode 100644 index 0000000..c5350b8 --- /dev/null +++ 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 new file mode 100644 index 0000000..6a3715a --- /dev/null +++ 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 index 80e7339..ff50453 100644 --- 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 index ff62160..a92433e 100644 --- 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 index 699ffdd..88578b3 100644 --- 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:: - - 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 - Objects can not be modified once they have been created. +This is the common interface for all Git objects: + +.. 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 -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 ------------------ +.. autoclass:: pygit2.Tree + :members: + :show-inheritance: + :undoc-members: -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 +.. 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 index d56ec70..2adce48 100644 --- 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 index 551717f..35f46d2 100644 --- a/docs/repository.rst +++ b/docs/repository.rst @@ -2,13 +2,11 @@ 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 @@ -16,9 +14,9 @@ Or by creating a new one:: >>> 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 new file mode 100644 index 0000000..42d0d63 --- /dev/null +++ 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 index c0ccee1..ab13948 100644 --- 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 index c990fd2..d20f7f1 100644 --- 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 index cb8425d..720ed38 100644 --- 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} };