docs: working on the repository chapter (in progress)

docs/repository.rst

@@ -2,21 +2,27 @@
 The repository
 **********************************************************************
 
-Everything starts by opening an existing repository::
+.. autofunction:: pygit2.init_repository
 
-    >>> from pygit2 import Repository
+   This is how to create non-bare 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
-
 .. autofunction:: pygit2.discover_repository
 
+
 .. autoclass:: pygit2.Repository
-   :members:
+   :members: path, workdir, is_bare, is_empty, revparse_single, read, write,
+             create_blob, create_blob_fromfile, create_commit,
+             create_reference, create_tag, TreeBuilder, walk,
+             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')

src/pygit2.c

@@ -58,6 +58,11 @@ extern PyTypeObject RefLogEntryType;
 extern PyTypeObject SignatureType;
 
 
+
+PyDoc_STRVAR(init_repository__doc__,
+  "init_repository(path, bare) -> Repository\n\n"
+  "Creates a new Git repository in the given path.");
+
 PyObject *
 init_repository(PyObject *self, PyObject *args)
 {
@@ -86,6 +91,11 @@ init_repository(PyObject *self, PyObject *args)
     return NULL;
 };
 
+
+PyDoc_STRVAR(discover_repository__doc__,
+  "discover_repository(path[, across_fs[, ceiling_dirs]]) -> str\n\n"
+  "Look for a git repository and return its path.");
+
 PyObject *
 discover_repository(PyObject *self, PyObject *args)
 {
@@ -107,10 +117,9 @@ discover_repository(PyObject *self, PyObject *args)
 };
 
 PyMethodDef module_methods[] = {
-    {"init_repository", init_repository, METH_VARARGS,
+    {"init_repository", init_repository, METH_VARARGS, init_repository__doc__},
-     "Creates a new Git repository in the given folder."},
     {"discover_repository", discover_repository, METH_VARARGS,
-     "Look for a git repository and return its path."},
+     discover_repository__doc__},
     {NULL}
 };
 

src/pygit2/repository.c

@@ -194,8 +194,12 @@ Repository_as_iter(Repository *self)
     return PyObject_GetIter(accum);
 }
 
+
+PyDoc_STRVAR(Repository_head__doc__,
+  "Current head reference of the repository.");
+
 PyObject *
-Repository_head(Repository *self)
+Repository_get_head(Repository *self)
 {
     git_reference *head;
     const git_oid *oid;
@@ -219,11 +223,9 @@ Repository_head(Repository *self)
 }
 
 
-PyDoc_STRVAR(
+PyDoc_STRVAR(Repository_head_is_detached__doc__,
-  Repository_head_is_detached_doc,
+  "A repository's HEAD is detached when it points directly to a commit "
-  "A repository's HEAD is detached when it points directly to a commit\n"
+  "instead of a branch.");
-  "instead of a branch.\n"
-);
 
 PyObject *
 Repository_head_is_detached(Repository *self)
@@ -235,11 +237,9 @@ Repository_head_is_detached(Repository *self)
 }
 
 
-PyDoc_STRVAR(
+PyDoc_STRVAR(Repository_head_is_orphaned__doc__,
-  Repository_head_is_orphaned_doc,
+  "An orphan branch is one named from HEAD but which doesn't exist in the "
-  "An orphan branch is one named from HEAD but which doesn't exist in\n"
+  "refs namespace, because it doesn't have any commit to point to.");
-  "the refs namespace, because it doesn't have any commit to point to.\n"
-);
 
 PyObject *
 Repository_head_is_orphaned(Repository *self)
@@ -251,10 +251,8 @@ Repository_head_is_orphaned(Repository *self)
 }
 
 
-PyDoc_STRVAR(
+PyDoc_STRVAR(Repository_is_empty__doc__,
-  Repository_is_empty_doc,
+  "Check if a repository is empty.");
-  "Check if a repository is empty\n"
-);
 
 PyObject *
 Repository_is_empty(Repository *self)
@@ -266,10 +264,8 @@ Repository_is_empty(Repository *self)
 }
 
 
-PyDoc_STRVAR(
+PyDoc_STRVAR(Repository_is_bare__doc__,
-  Repository_is_bare_doc,
+  "Check if a repository is a bare repository.");
-  "Check if a repository is a bare repository.\n"
-);
 
 PyObject *
 Repository_is_bare(Repository *self)
@@ -403,6 +399,9 @@ Repository_write(Repository *self, PyObject *args)
     return git_oid_to_python(oid.id);
 }
 
+
+PyDoc_STRVAR(Repository_index__doc__, "Index file.");
+
 PyObject *
 Repository_get_index(Repository *self, void *closure)
 {
@@ -434,12 +433,21 @@ Repository_get_index(Repository *self, void *closure)
     return self->index;
 }
 
+
+PyDoc_STRVAR(Repository_path__doc__,
+  "The normalized path to the git repository.");
+
 PyObject *
 Repository_get_path(Repository *self, void *closure)
 {
     return to_path(git_repository_path(self->repo));
 }
 
+
+PyDoc_STRVAR(Repository_workdir__doc__,
+  "The normalized path to the working directory of the repository. "
+  "If the repository is bare, None will be returned.");
+
 PyObject *
 Repository_get_workdir(Repository *self, void *closure)
 {
@@ -452,6 +460,13 @@ Repository_get_workdir(Repository *self, void *closure)
     return to_path(c_path);
 }
 
+
+PyDoc_STRVAR(Repository_config__doc__,
+  "Get the configuration file for this repository.\n\n"
+  "If a configuration file has not been set, the default config set for the "
+  "repository will be returned, including global and system configurations "
+  "(if they are available).");
+
 PyObject *
 Repository_get_config(Repository *self, void *closure)
 {
@@ -568,6 +583,12 @@ Repository_create_blob_fromfile(Repository *self, PyObject *args)
     return git_oid_to_python(oid.id);
 }
 
+
+PyDoc_STRVAR(Repository_create_commit__doc__,
+  "create_commit(reference, author, committer, message, tree, parents"
+  "[, encoding]) -> bytes\n\n"
+  "Create a new commit object, return its SHA.");
+
 PyObject *
 Repository_create_commit(Repository *self, PyObject *args)
 {
@@ -906,7 +927,7 @@ Repository_TreeBuilder(Repository *self, PyObject *args)
 
 PyMethodDef Repository_methods[] = {
     {"create_commit", (PyCFunction)Repository_create_commit, METH_VARARGS,
-     "Create a new commit object, return its SHA."},
+     Repository_create_commit__doc__},
     {"create_tag", (PyCFunction)Repository_create_tag, METH_VARARGS,
      "Create a new tag object, return its SHA."},
     {"walk", (PyCFunction)Repository_walk, METH_VARARGS,
@@ -948,27 +969,21 @@ PyMethodDef Repository_methods[] = {
 };
 
 PyGetSetDef Repository_getseters[] = {
-    {"index", (getter)Repository_get_index, NULL, "index file. ", NULL},
+    {"index", (getter)Repository_get_index, NULL, Repository_index__doc__,
-    {"path", (getter)Repository_get_path, NULL,
+     NULL},
-     "The normalized path to the git repository.", NULL},
+    {"path", (getter)Repository_get_path, NULL, Repository_path__doc__, NULL},
-    {"head", (getter)Repository_head, NULL,
+    {"head", (getter)Repository_get_head, NULL, Repository_head__doc__, NULL},
-      "Current head reference of the repository.", NULL},
     {"head_is_detached", (getter)Repository_head_is_detached, NULL,
-     Repository_head_is_detached_doc},
+     Repository_head_is_detached__doc__},
     {"head_is_orphaned", (getter)Repository_head_is_orphaned, NULL,
-     Repository_head_is_orphaned_doc},
+     Repository_head_is_orphaned__doc__},
     {"is_empty", (getter)Repository_is_empty, NULL,
-     Repository_is_empty_doc},
+     Repository_is_empty__doc__},
-    {"is_bare", (getter)Repository_is_bare, NULL,
+    {"is_bare", (getter)Repository_is_bare, NULL, Repository_is_bare__doc__},
-     Repository_is_bare_doc},
+    {"config", (getter)Repository_get_config, NULL, Repository_config__doc__,
-    {"config", (getter)Repository_get_config, NULL,
+     NULL},
-     "Get the configuration file for this repository.\n\n"
-     "If a configuration file has not been set, the default "
-     "config set for the repository will be returned, including "
-     "global and system configurations (if they are available).", NULL},
     {"workdir", (getter)Repository_get_workdir, NULL,
-     "The normalized path to the working directory of the repository. "
+     Repository_workdir__doc__, NULL},
-     "If the repository is bare, None will be returned.", NULL},
     {NULL}
 };
 
@@ -989,6 +1004,11 @@ PyMappingMethods Repository_as_mapping = {
     0,                               /* mp_ass_subscript */
 };
 
+
+PyDoc_STRVAR(Repository__doc__,
+    "Repository(path) -> Repository\n\n"
+    "Git repository.");
+
 PyTypeObject RepositoryType = {
     PyVarObject_HEAD_INIT(NULL, 0)
     "_pygit2.Repository",                       /* tp_name           */
@@ -1012,7 +1032,7 @@ PyTypeObject RepositoryType = {
     Py_TPFLAGS_DEFAULT |
     Py_TPFLAGS_BASETYPE |
     Py_TPFLAGS_HAVE_GC,                        /* tp_flags          */
-    "Git repository",                          /* tp_doc            */
+    Repository__doc__,                         /* tp_doc            */
     (traverseproc)Repository_traverse,         /* tp_traverse       */
     (inquiry)Repository_clear,                 /* tp_clear          */
     0,                                         /* tp_richcompare    */