restructured recipes

docs/examples.rst

@@ -1,41 +0,0 @@
-**********************************************************************
-Quick examples
-**********************************************************************
-
-A list of some common command-line operations and their pygit2 equivalents.
-
-Creating a new repository with ``git init``
-
-    >>> pygit2.init_repository('repo_name', False)
-    <pygit2.repository.Repository object at 0x10f08b680>
-
-Viewing a commit with ``git show d370f56``
-
-    >>> repo = pygit2.Repository('/path/to/repository')
-    >>> commit = repo['d370f56']
-
-Viewing the last commit message
-
-    >>> repo[repo.head.oid].message
-    'commit message'
-
-Traversing the commit history with ``git log``
-
-    >>> last = repo[repo.head.oid]
-    >>> for commit in repo.walk(last.oid, pygit2.GIT_SORT_TIME):
-    >>>     print(commit.message) # or some other operation
-
-Listing all branches with ``git branch``
-
-    >>> regex = re.compile('^refs/heads/')
-    >>> filter(lambda r: regex.match(r), repo.listall_references())
-
-Similarly, listing all tags with ``git tag``
-
-    >>> regex = re.compile('^refs/tags')
-    >>> filter(lambda r: regex.match(r), repo.listall_references())
-
-Listing all files in the last commit
-
-    >>> for e in repo[repo.head.oid].tree:
-    >>>     print(e.name)

docs/index.rst

@@ -25,7 +25,7 @@ Start:
    :maxdepth: 1
 
    install
-   examples
+   recipes
 
 Usage guide:
 

docs/recipes.rst

@@ -0,0 +1,26 @@
+**********************************************************************
+pygit2 Recipes
+**********************************************************************
+
+A list of some standard git commands and their pygit2 equivalents. This
+document is a work in progress, and is organized according to the `git man
+page`_.
+
+----------------------------------------------------------------------
+High Level Commands
+----------------------------------------------------------------------
+
+======================================================================
+Main porcelain commands
+======================================================================
+
+.. toctree::
+   :maxdepth: 1
+
+   git-branch (List, create, or delete branches.) <recipes/git-branch>
+   git-init (Create an empty git repository or reinitialize an existing one.) <recipes/git-init>
+   git-log (Show commit logs.) <recipes/git-log>
+   git-show (Show various types of objects.) <recipes/git-show>
+   git-tag (Create, list, delete or verify a tag object signed with GPG.) <recipes/git-tag>
+
+.. _git man page: https://www.kernel.org/pub/software/scm/git/docs/git.html

docs/recipes/git-branch.rst

@@ -0,0 +1,30 @@
+**********************************************************************
+git-branch
+**********************************************************************
+
+----------------------------------------------------------------------
+Listing branches
+----------------------------------------------------------------------
+
+======================================================================
+List all branches
+======================================================================
+
+.. code-block:: bash
+
+    $> git branch
+
+.. code-block:: python
+
+    >>> regex = re.compile('^refs/heads/')
+    >>> branches = filter(lambda r: regex.match(r), repo.listall_references())
+
+`Note that the next release will probably allow` ``repo.listall_branches()``.
+
+----------------------------------------------------------------------
+References
+----------------------------------------------------------------------
+
+- git-branch_.
+
+.. _git-branch: https://www.kernel.org/pub/software/scm/git/docs/git-branch.html

docs/recipes/git-init.rst

@@ -0,0 +1,41 @@
+**********************************************************************
+git-init
+**********************************************************************
+
+----------------------------------------------------------------------
+Creating a new repository
+----------------------------------------------------------------------
+
+======================================================================
+Create bare repository
+======================================================================
+
+.. code-block:: bash
+
+    $> git init --bare relative/path
+
+.. code-block:: python
+
+    >>> pygit2.init_repository('relative/path', True)
+    <pygit2.repository.Repository object at 0x10f08b680>
+
+======================================================================
+Create standard repository
+======================================================================
+
+.. code-block:: bash
+
+    $> git init relative/path
+
+.. code-block:: python
+
+    >>> pygit2.init_repository('relative/path', False)
+    <pygit2.repository.Repository object at 0x10f08b680>
+
+----------------------------------------------------------------------
+References
+----------------------------------------------------------------------
+
+- git-init_.
+
+.. _git-init: https://www.kernel.org/pub/software/scm/git/docs/git-init.html

docs/recipes/git-log.rst

@@ -0,0 +1,43 @@
+**********************************************************************
+git-log
+**********************************************************************
+
+----------------------------------------------------------------------
+Showing HEAD commit logs
+----------------------------------------------------------------------
+
+======================================================================
+Show HEAD commit
+======================================================================
+
+.. code-block:: bash
+
+    $> git log -1
+
+.. code-block:: python
+
+    >>> commit = repo[repo.head.oid]
+    >>> commit.message
+    'commit message'
+
+======================================================================
+Traverse commit history
+======================================================================
+
+.. code-block:: bash
+
+    $> git log
+
+.. code-block:: python
+
+    >>> last = repo[repo.head.oid]
+    >>> for commit in repo.walk(last.oid, pygit2.GIT_SORT_TIME):
+    >>>     print(commit.message) # or some other operation
+
+----------------------------------------------------------------------
+References
+----------------------------------------------------------------------
+
+- git-log_.
+
+.. _git-log: https://www.kernel.org/pub/software/scm/git/docs/git-log.html

docs/recipes/git-show.rst

@@ -0,0 +1,49 @@
+**********************************************************************
+git-show
+**********************************************************************
+
+----------------------------------------------------------------------
+Showing a commit
+----------------------------------------------------------------------
+
+.. code-block:: bash
+
+    $> git show d370f56
+
+.. code-block:: python
+
+    >>> repo = pygit2.Repository('/path/to/repository')
+    >>> commit = repo.revparse_single('d370f56')
+
+======================================================================
+Show log message
+======================================================================
+
+    >>> message = commit.message
+
+======================================================================
+Show SHA hash
+======================================================================
+
+    >>> hash = commit.hex
+
+======================================================================
+Show diff
+======================================================================
+
+    >>> diff = commit.tree.diff()
+
+======================================================================
+Show all files in commit
+======================================================================
+
+    >>> for e in commit.tree:
+    >>>     print(e.name)
+
+----------------------------------------------------------------------
+References
+----------------------------------------------------------------------
+
+- git-show_.
+
+.. _git-show: https://www.kernel.org/pub/software/scm/git/docs/git-show.html

docs/recipes/git-tag.rst

@@ -0,0 +1,24 @@
+**********************************************************************
+git-tag
+**********************************************************************
+
+----------------------------------------------------------------------
+Showing all tags
+----------------------------------------------------------------------
+
+.. code-block:: bash
+
+    $> git tag
+
+.. code-block:: python
+
+    >>> regex = re.compile('^refs/tags')
+    >>> filter(lambda r: regex.match(r), repo.listall_references())
+
+----------------------------------------------------------------------
+References
+----------------------------------------------------------------------
+
+- git-tag_.
+
+.. _git-tag: https://www.kernel.org/pub/software/scm/git/docs/git-tag.html