docs: complete and improve organization

docs/config.rst

@@ -1,8 +1,18 @@
 **********************************************************************
-Configuration file
+Configuration files
 **********************************************************************
 
-.. autoclass:: pygit2.Config
+.. autoattribute:: pygit2.Repository.config
-   :members:
+
-   :show-inheritance:
+
-   :undoc-members:
+The Config type
+================
+
+.. automethod:: pygit2.Config.get_system_config
+.. automethod:: pygit2.Config.get_global_config
+.. automethod:: pygit2.Config.foreach
+.. automethod:: pygit2.Config.add_file
+.. automethod:: pygit2.Config.get_multivar
+.. automethod:: pygit2.Config.set_multivar
+
+The :class:`Config` Mapping interface.

docs/diff.rst

@@ -2,7 +2,6 @@
 Diff
 **********************************************************************
 
-
 A diff shows the changes between trees, an index or the working dir::
 
     # Diff two trees
@@ -19,12 +18,32 @@ A diff shows the changes between trees, an index or the working dir::
     >>> tree = repo.head.tree
     >>> diff = tree.diff()
 
-The interface for a diff::
 
-    Diff.changes          -- Dict of 'files' and 'hunks' for every change
+The Diff type
-    Diff.patch            -- a patch for every changeset
+====================
-    Diff.merge            -- Merge two Diffs
+
+.. autoattribute:: pygit2.Diff.patch
+.. automethod:: pygit2.Diff.merge
+.. automethod:: pygit2.Diff.find_similar
 
 
-.. autoclass:: pygit2.Diff
+The Patch type
-   :members:
+====================
+
+.. autoattribute:: pygit2.Patch.old_file_path
+.. autoattribute:: pygit2.Patch.new_file_path
+.. autoattribute:: pygit2.Patch.old_oid
+.. autoattribute:: pygit2.Patch.new_oid
+.. autoattribute:: pygit2.Patch.status
+.. autoattribute:: pygit2.Patch.similarity
+.. autoattribute:: pygit2.Patch.hunks
+
+
+The Hunk type
+====================
+
+.. autoattribute:: pygit2.Hunk.old_start
+.. autoattribute:: pygit2.Hunk.old_lines
+.. autoattribute:: pygit2.Hunk.new_start
+.. autoattribute:: pygit2.Hunk.new_lines
+.. autoattribute:: pygit2.Hunk.lines

docs/index-file.rst

@@ -1,28 +0,0 @@
-**********************************************************************
-Index file
-**********************************************************************
-
-Index read::
-
-    >>> index = repo.index
-    >>> index.read()
-    >>> oid = index['path/to/file'].oid    # from path to object id
-    >>> blob = repo[oid]                   # from object id to object
-
-Iterate over all entries of the index::
-
-    >>> for entry in index:
-    ...     print entry.path, entry.hex
-
-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
-
-
-.. autoclass:: pygit2.Index
-   :members: add, remove, clear, read, write, read_tree, write_tree, diff
-
-.. autoclass:: pygit2.IndexEntry
-   :members: oid, hex, path, mode

docs/index.rst

@@ -36,10 +36,10 @@ Usage guide:
    references
    revparse
    log
+   working-copy
    diff
-   index-file
-   status
    config
+   remotes
    errors
 
 More:

docs/log.rst

@@ -2,6 +2,8 @@
 Commit log
 **********************************************************************
 
+.. automethod:: pygit2.Repository.walk
+
 You can iterate through the revision history with repo.walk::
 
     >>> from pygit2 import GIT_SORT_TIME

docs/objects.rst

@@ -37,24 +37,30 @@ Objects can not be modified once they have been created.
 
 This is the common interface for all Git objects:
 
-.. autoclass:: pygit2.Object
+.. autoattribute:: pygit2.Object.oid
-   :members: type, oid, hex, read_raw
+.. autoattribute:: pygit2.Object.hex
+.. autoattribute:: pygit2.Object.type
+.. automethod:: pygit2.Object.read_raw
 
 
 Commits
------------------
+=================
 
 A commit is a snapshot of the working dir with meta informations like author,
 committer and others.
 
-.. autoclass:: pygit2.Commit
+.. autoattribute:: pygit2.Commit.author
-   :members: author, committer, message, message_encoding, tree, parents,
+.. autoattribute:: pygit2.Commit.committer
-             commit_time, commit_time_offset
+.. autoattribute:: pygit2.Commit.message
-   :show-inheritance:
+.. autoattribute:: pygit2.Commit.message_encoding
+.. autoattribute:: pygit2.Commit.tree
+.. autoattribute:: pygit2.Commit.parents
+.. autoattribute:: pygit2.Commit.commit_time
+.. autoattribute:: pygit2.Commit.commit_time_offset
 
 
 Signatures
-.............
+-------------
 
 The author and committer attributes of commit objects are ``Signature``
 objects::
@@ -62,12 +68,16 @@ objects::
     >>> commit.author
     <pygit2.Signature object at 0x7f75e9b1f5f8>
 
-.. autoclass:: pygit2.Signature
+.. autoattribute:: pygit2.Signature.name
-   :members: name, email, time, offset
+.. autoattribute:: pygit2.Signature.email
+.. autoattribute:: pygit2.Signature.time
+.. autoattribute:: pygit2.Signature.offset
 
 
 Creating commits
-................
+----------------
+
+.. automethod:: pygit2.Repository.create_commit
 
 Commits can be created by calling the ``create_commit`` method of the
 repository with the following parameters::
@@ -85,7 +95,7 @@ repository with the following parameters::
 
 
 Trees
------------------
+=================
 
 A tree is a sorted collection of tree entries. It is similar to a folder or
 directory in a file system. Each entry points to another tree or a blob.  A
@@ -118,19 +128,28 @@ interfaces::
     >>> blob
     <pygit2.Blob object at 0xcc12d0>
 
-.. autoclass:: pygit2.Tree
+.. automethod:: pygit2.Tree.diff
-   :members:
-   :show-inheritance:
-   :undoc-members:
 
-.. autoclass:: pygit2.TreeEntry
+.. autoattribute:: pygit2.TreeEntry.name
-   :members: name, oid, hex, filemode, to_object
+.. autoattribute:: pygit2.TreeEntry.oid
-   :show-inheritance:
+.. autoattribute:: pygit2.TreeEntry.hex
-   :undoc-members:
+.. autoattribute:: pygit2.TreeEntry.filemode
+.. automethod:: pygit2.TreeEntry.to_object
+
+
+Creating trees
+--------------------
+
+.. automethod:: pygit2.Repository.TreeBuilder
+
+.. automethod:: pygit2.TreeBuilder.insert
+.. automethod:: pygit2.TreeBuilder.remove
+.. automethod:: pygit2.TreeBuilder.clear
+.. automethod:: pygit2.TreeBuilder.write
 
 
 Blobs
------------------
+=================
 
 A blob is equivalent to a file in a file system.::
 
@@ -142,19 +161,28 @@ A blob is equivalent to a file in a file system.::
     >>> oid
     '\x96\xc9\x06um{\x91\xc4S"a|\x92\x95\xe4\xa8\rR\xd1\xc5'
 
-.. autoclass:: pygit2.Blob
+.. autoattribute:: pygit2.Blob.data
-   :members:
+.. autoattribute:: pygit2.Blob.size
-   :show-inheritance:
+
-   :undoc-members:
+Creating blobs
+--------------------
+
+.. automethod:: pygit2.Repository.create_blob
+.. automethod:: pygit2.Repository.create_blob_fromfile
 
 
 Tags
------------------
+=================
 
 A tag is a static label for a commit. See references for more information.
 
+.. autoattribute:: pygit2.Tag.name
+.. autoattribute:: pygit2.Tag.target
+.. autoattribute:: pygit2.Tag.tagger
+.. autoattribute:: pygit2.Tag.message
 
-.. autoclass:: pygit2.Tag
+
-   :members:
+Creating tags
-   :show-inheritance:
+--------------------
-   :undoc-members:
+
+.. automethod:: pygit2.Repository.create_tag

docs/references.rst

@@ -2,6 +2,9 @@
 References
 **********************************************************************
 
+.. automethod:: pygit2.Repository.listall_references
+.. automethod:: pygit2.Repository.lookup_reference
+
 Reference lookup::
 
     >>> all_refs = repo.listall_references()
@@ -22,9 +25,42 @@ The interface for RefLogEntry::
     RefLogEntry.oid_new   -- oid of new reference
 
 
-.. Autogenerated
+The Reference type
+====================
 
-.. autoclass:: pygit2.Reference
+.. autoattribute:: pygit2.Reference.name
-   :members:
+.. autoattribute:: pygit2.Reference.oid
-   :show-inheritance:
+.. autoattribute:: pygit2.Reference.hex
-   :undoc-members:
+.. autoattribute:: pygit2.Reference.target
+.. autoattribute:: pygit2.Reference.type
+
+.. automethod:: pygit2.Reference.delete
+.. automethod:: pygit2.Reference.rename
+.. automethod:: pygit2.Reference.resolve
+.. automethod:: pygit2.Reference.log
+
+
+The reference log
+--------------------
+
+.. autoattribute:: pygit2.RefLogEntry.oid_new
+.. autoattribute:: pygit2.RefLogEntry.oid_old
+.. autoattribute:: pygit2.RefLogEntry.message
+.. autoattribute:: pygit2.RefLogEntry.committer
+
+
+Notes
+====================
+
+.. automethod:: pygit2.Repository.notes
+.. automethod:: pygit2.Repository.create_note
+.. automethod:: pygit2.Repository.lookup_note
+
+
+The Note type
+--------------------
+
+.. autoattribute:: pygit2.Note.annotated_id
+.. autoattribute:: pygit2.Note.oid
+.. autoattribute:: pygit2.Note.message
+.. automethod:: pygit2.Note.remove

docs/remotes.rst

@@ -0,0 +1,16 @@
+**********************************************************************
+Remotes
+**********************************************************************
+
+
+.. autoattribute:: pygit2.Repository.remotes
+.. automethod:: pygit2.Repository.create_remote
+
+
+The Remote type
+====================
+
+.. autoattribute:: pygit2.Remote.name
+.. autoattribute:: pygit2.Remote.url
+.. autoattribute:: pygit2.Remote.fetchspec
+.. automethod:: pygit2.Remote.fetch

docs/repository.rst

@@ -2,34 +2,45 @@
 The repository
 **********************************************************************
 
+Everything starts either by creating a new repository, or by opening an
+existing one.
+
+
+Creating a repository
+===================================
+
 .. autofunction:: pygit2.init_repository
 
-   This is how to create non-bare repository::
+This is how to create non-bare repository::
 
   >>> from pygit2 import init_repository
   >>> repo = init_repository('test')
 
-   And this is how to create a bare repository::
+And this is how to create a bare repository::
 
   >>> from pygit2 import init_repository
   >>> repo = init_repository('test', bare=True)
 
-   But one can also do::
+But one can also do::
 
   >>> from pygit2 import init_repository
   >>> repo = init_repository('test', True)
 
-.. autofunction:: pygit2.discover_repository
 
+The Repository class
+===================================
 
-.. autoclass:: pygit2.Repository
+To open an existing repository::
-   :members: path, workdir, is_bare, is_empty, revparse_single, read, write,
-             create_blob, create_blob_fromfile, create_commit, create_tag,
-             TreeBuilder, walk, create_reference, listall_references,
-             lookup_reference, packall_references, head, head_is_detached,
-             head_is_orphaned, index, status, status_file, config
-
-   To open an existing repository::
 
   >>> from pygit2 import Repository
   >>> repo = Repository('pygit2/.git')
+
+.. autoattribute:: pygit2.Repository.path
+.. autoattribute:: pygit2.Repository.workdir
+.. autoattribute:: pygit2.Repository.is_bare
+.. autoattribute:: pygit2.Repository.is_empty
+.. automethod:: pygit2.Repository.read
+.. automethod:: pygit2.Repository.write
+.. autoattribute:: pygit2.Repository.head
+.. autoattribute:: pygit2.Repository.head_is_detached
+.. autoattribute:: pygit2.Repository.head_is_orphaned

docs/revparse.rst

@@ -2,6 +2,8 @@
 Revision parsing
 **********************************************************************
 
+.. automethod:: pygit2.Repository.revparse_single
+
 You can use any of the fancy `<rev>` forms supported by libgit2::
 
     >>> commit = repo.revparse_single('HEAD^')

docs/status.rst

@@ -1,11 +0,0 @@
-**********************************************************************
-Status
-**********************************************************************
-
-Inspect the status of the repository::
-
-    >>> from pygit2 import GIT_STATUS_CURRENT
-    >>> status = repo.status()
-    >>> for filepath, flags in status.items():
-    ...     if flags != GIT_STATUS_CURRENT:
-    ...         print "Filepath %s isn't clean" % filepath

docs/utils.rst

@@ -2,6 +2,12 @@
 Utilities
 **********************************************************************
 
+.. autofunction:: pygit2.discover_repository
+
+.. autofunction:: pygit2.hash
+
+.. autofunction:: pygit2.hashfile
+
 .. automodule:: pygit2.utils
    :members:
    :show-inheritance:

docs/working-copy.rst

@@ -0,0 +1,66 @@
+**********************************************************************
+The Index file and the Working copy
+**********************************************************************
+
+.. autoattribute:: pygit2.Repository.index
+
+Index read::
+
+    >>> index = repo.index
+    >>> index.read()
+    >>> oid = index['path/to/file'].oid    # from path to object id
+    >>> blob = repo[oid]                   # from object id to object
+
+Iterate over all entries of the index::
+
+    >>> for entry in index:
+    ...     print entry.path, entry.hex
+
+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
+
+
+The Index type
+====================
+
+.. automethod:: pygit2.Index.add
+.. automethod:: pygit2.Index.remove
+.. automethod:: pygit2.Index.clear
+.. automethod:: pygit2.Index.read
+.. automethod:: pygit2.Index.write
+.. automethod:: pygit2.Index.read_tree
+.. automethod:: pygit2.Index.write_tree
+.. automethod:: pygit2.Index.diff
+
+
+The IndexEntry type
+--------------------
+
+.. autoattribute:: pygit2.IndexEntry.oid
+.. autoattribute:: pygit2.IndexEntry.hex
+.. autoattribute:: pygit2.IndexEntry.path
+.. autoattribute:: pygit2.IndexEntry.mode
+
+
+Status
+====================
+
+.. automethod:: pygit2.Repository.status
+.. automethod:: pygit2.Repository.status_file
+
+Inspect the status of the repository::
+
+    >>> from pygit2 import GIT_STATUS_CURRENT
+    >>> status = repo.status()
+    >>> for filepath, flags in status.items():
+    ...     if flags != GIT_STATUS_CURRENT:
+    ...         print "Filepath %s isn't clean" % filepath
+
+
+Checkout
+====================
+
+.. automethod:: pygit2.Repository.checkout

pygit2/__init__.py

@@ -41,6 +41,14 @@ import pygit2.utils
 def init_repository(path, bare=False):
     """
     Creates a new Git repository in the given path.
+
+    Arguments:
+
+    path
+      Path where to create the repository.
+
+    bare
+      Whether the repository will be bare or not.
     """
     _pygit2.init_repository(path, bare)
     return Repository(path)

src/pygit2.c

@@ -68,7 +68,15 @@ extern PyTypeObject NoteIterType;
 PyDoc_STRVAR(init_repository__doc__,
     "init_repository(path, bare)\n"
     "\n"
-  "Creates a new Git repository in the given path.");
+    "Creates a new Git repository in the given path.\n"
+    "\n"
+    "Arguments:\n"
+    "\n"
+    "path\n"
+    "  Path where to create the repository.\n"
+    "\n"
+    "bare\n"
+    "  Whether the repository will be bare or not.\n");
 
 PyObject *
 init_repository(PyObject *self, PyObject *args) {
@@ -115,7 +123,7 @@ discover_repository(PyObject *self, PyObject *args)
 };
 
 PyDoc_STRVAR(hashfile__doc__,
-  "hash(path) -> bytes\n"
+  "hashfile(path) -> bytes\n"
   "\n"
   "Returns the oid of a new blob from a file path without actually writing \n"
   "to the odb.");
@@ -176,10 +184,15 @@ moduleinit(PyObject* m)
     if (m == NULL)
         return NULL;
 
+    /* Errors */
     GitError = PyErr_NewException("_pygit2.GitError", NULL, NULL);
+    Py_INCREF(GitError);
+    PyModule_AddObject(m, "GitError", GitError);
 
     /* Repository */
     INIT_TYPE(RepositoryType, NULL, PyType_GenericNew)
+    ADD_TYPE(m, Repository);
+
     /* Objects (make them with the Repository.create_XXX methods). */
     INIT_TYPE(ObjectType, NULL, NULL)
     INIT_TYPE(CommitType, &ObjectType, NULL)
@@ -190,77 +203,53 @@ moduleinit(PyObject* m)
     INIT_TYPE(TreeBuilderType, NULL, PyType_GenericNew)
     INIT_TYPE(BlobType, &ObjectType, NULL)
     INIT_TYPE(TagType, &ObjectType, NULL)
+    ADD_TYPE(m, Object);
+    ADD_TYPE(m, Commit);
+    ADD_TYPE(m, Signature);
+    ADD_TYPE(m, Tree);
+    ADD_TYPE(m, TreeEntry);
+    ADD_TYPE(m, TreeBuilder);
+    ADD_TYPE(m, Blob);
+    ADD_TYPE(m, Tag);
+
     /* References */
     INIT_TYPE(ReferenceType, NULL, PyType_GenericNew)
     INIT_TYPE(RefLogEntryType, NULL, NULL)
     INIT_TYPE(RefLogIterType, NULL, NULL)
+    INIT_TYPE(NoteType, NULL, NULL)
+    INIT_TYPE(NoteIterType, NULL, NULL)
+    ADD_TYPE(m, Reference);
+    ADD_TYPE(m, RefLogEntry);
+    ADD_TYPE(m, Note);
+
     /* Index */
     INIT_TYPE(IndexType, NULL, PyType_GenericNew)
     INIT_TYPE(IndexEntryType, NULL, PyType_GenericNew)
     INIT_TYPE(IndexIterType, NULL, NULL)
+    ADD_TYPE(m, Index);
+    ADD_TYPE(m, IndexEntry);
+
     /* Diff */
     INIT_TYPE(DiffType, NULL, NULL)
     INIT_TYPE(DiffIterType, NULL, NULL)
     INIT_TYPE(PatchType, NULL, NULL)
     INIT_TYPE(HunkType, NULL, NULL)
+    ADD_TYPE(m, Diff);
+    ADD_TYPE(m, Patch);
+    ADD_TYPE(m, Hunk);
+
     /* Log */
     INIT_TYPE(WalkerType, NULL, PyType_GenericNew)
+
     /* Config */
     INIT_TYPE(ConfigType, NULL, PyType_GenericNew)
+    ADD_TYPE(m, Config);
+
     /* Remote */
     INIT_TYPE(RemoteType, NULL, NULL)
-    /* Notes */
+    ADD_TYPE(m, Remote);
-    INIT_TYPE(NoteType, NULL, NULL)
-    INIT_TYPE(NoteIterType, NULL, NULL)
-
-    Py_INCREF(GitError);
-    PyModule_AddObject(m, "GitError", GitError);
-
-    Py_INCREF(&RepositoryType);
-    PyModule_AddObject(m, "Repository", (PyObject *)&RepositoryType);
-
-    Py_INCREF(&ObjectType);
-    PyModule_AddObject(m, "Object", (PyObject *)&ObjectType);
-
-    Py_INCREF(&CommitType);
-    PyModule_AddObject(m, "Commit", (PyObject *)&CommitType);
-
-    Py_INCREF(&TreeEntryType);
-    PyModule_AddObject(m, "TreeEntry", (PyObject *)&TreeEntryType);
-
-    Py_INCREF(&TreeType);
-    PyModule_AddObject(m, "Tree", (PyObject *)&TreeType);
-
-    Py_INCREF(&ConfigType);
-    PyModule_AddObject(m, "Config", (PyObject *)&ConfigType);
-
-    Py_INCREF(&BlobType);
-    PyModule_AddObject(m, "Blob", (PyObject *)&BlobType);
-
-    Py_INCREF(&TagType);
-    PyModule_AddObject(m, "Tag", (PyObject *)&TagType);
-
-    Py_INCREF(&IndexType);
-    PyModule_AddObject(m, "Index", (PyObject *)&IndexType);
-
-    Py_INCREF(&IndexEntryType);
-    PyModule_AddObject(m, "IndexEntry", (PyObject *)&IndexEntryType);
-
-    Py_INCREF(&DiffType);
-    PyModule_AddObject(m, "Diff", (PyObject *)&DiffType);
-
-    Py_INCREF(&ReferenceType);
-    PyModule_AddObject(m, "Reference", (PyObject *)&ReferenceType);
-
-    Py_INCREF(&SignatureType);
-    PyModule_AddObject(m, "Signature", (PyObject *)&SignatureType);
-
-    Py_INCREF(&RemoteType);
-    PyModule_AddObject(m, "Remote", (PyObject *)&RemoteType);
-
-    Py_INCREF(&NoteType);
-    PyModule_AddObject(m, "Note", (PyObject *)&NoteType);
 
+    /* Constants */
     PyModule_AddIntConstant(m, "GIT_OBJ_ANY", GIT_OBJ_ANY);
     PyModule_AddIntConstant(m, "GIT_OBJ_COMMIT", GIT_OBJ_COMMIT);
     PyModule_AddIntConstant(m, "GIT_OBJ_TREE", GIT_OBJ_TREE);

src/repository.c

@@ -1009,7 +1009,7 @@ Repository_TreeBuilder(Repository *self, PyObject *args)
 
 
 PyDoc_STRVAR(Repository_create_remote__doc__,
-  "remote_create(name, url) -> Remote\n"
+  "create_remote(name, url) -> Remote\n"
   "\n"
   "Creates a new remote.");
 
@@ -1036,7 +1036,7 @@ Repository_create_remote(Repository *self, PyObject *args)
 }
 
 
-PyDoc_STRVAR(Repository_remotes__doc__, "returns all configured remotes");
+PyDoc_STRVAR(Repository_remotes__doc__, "Returns all configured remotes.");
 
 PyObject *
 Repository_remotes__get__(Repository *self)

src/utils.h

@@ -141,5 +141,9 @@ char * py_str_to_c_str(PyObject *value, const char *encoding);
     if (new != NULL) type.tp_new = new; \
     if (PyType_Ready(&type) < 0) return NULL;
 
+#define ADD_TYPE(module, type) \
+    Py_INCREF(& type ## Type); \
+    PyModule_AddObject(module, #type, (PyObject *) & type ## Type);
+
 
 #endif