From e34911b63e5d2266f9f72a4e3f32e27b13190feb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=2E=20David=20Ib=C3=A1=C3=B1ez?= Date: Sun, 13 Jan 2013 22:26:49 +0100 Subject: [PATCH] docs: split usage guide into several source files --- docs/{reference.rst => autodoc.rst} | 2 +- docs/index-file.rst | 21 ++++++ docs/index.rst | 19 ++++- docs/log.rst | 9 +++ docs/{usage.rst => objects.rst} | 105 ++-------------------------- docs/references.rst | 22 ++++++ docs/repository.rst | 24 +++++++ docs/revparse.rst | 7 ++ docs/status.rst | 11 +++ 9 files changed, 116 insertions(+), 104 deletions(-) rename docs/{reference.rst => autodoc.rst} (93%) create mode 100644 docs/index-file.rst create mode 100644 docs/log.rst rename docs/{usage.rst => objects.rst} (69%) create mode 100644 docs/references.rst create mode 100644 docs/repository.rst create mode 100644 docs/revparse.rst create mode 100644 docs/status.rst diff --git a/docs/reference.rst b/docs/autodoc.rst similarity index 93% rename from docs/reference.rst rename to docs/autodoc.rst index 044ae54..fee3bdf 100644 --- a/docs/reference.rst +++ b/docs/autodoc.rst @@ -1,4 +1,4 @@ -Reference +API Reference ============= .. Util functions diff --git a/docs/index-file.rst b/docs/index-file.rst new file mode 100644 index 0000000..80e7339 --- /dev/null +++ b/docs/index-file.rst @@ -0,0 +1,21 @@ +********************************************************************** +The 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 diff --git a/docs/index.rst b/docs/index.rst index 10eb5f5..ff62160 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,14 +18,27 @@ Pygit2 links: - http://www.pygit2.org/ -- Documentation - http://pypi.python.org/pypi/pygit2 -- Download -Table of Contents: +Topics: + .. toctree:: :maxdepth: 2 install - usage - reference + autodoc + +Usage guide: + +.. toctree:: + :maxdepth: 1 + + repository + objects + references + revparse + log + index-file + status diff --git a/docs/log.rst b/docs/log.rst new file mode 100644 index 0000000..ea0378b --- /dev/null +++ b/docs/log.rst @@ -0,0 +1,9 @@ +********************************************************************** +Commit log +********************************************************************** + +You can iterate through the revision history with repo.walk:: + + >>> from pygit2 import GIT_SORT_TIME + >>> for commit in repo.walk(oid, GIT_SORT_TIME): + ... print(commit.hex) diff --git a/docs/usage.rst b/docs/objects.rst similarity index 69% rename from docs/usage.rst rename to docs/objects.rst index 83602f8..699ffdd 100644 --- a/docs/usage.rst +++ b/docs/objects.rst @@ -1,33 +1,10 @@ ********************************************************************** -Usage samples -********************************************************************** - -.. contents:: - - -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) - -These are the basic attributes of a repository:: - - Repository.path -- path to the Git repository - Repository.workdir -- path to the working directory, None in the case of - a bare repo - - Git objects -=========== +********************************************************************** + +.. contents:: Contents + :local: + In the first place Git is a key-value storage system. The values stored are called *objects*, there are four types (commits, trees, blobs and tags), @@ -201,75 +178,3 @@ Tags ----------------- A tag is a static label for a commit. See references for more information. - - - -References -================= - -Reference lookup:: - - >>> all_refs = repo.listall_references() - >>> master_ref = repo.lookup_reference("refs/heads/master") - >>> commit = repo[master_ref.oid] - -Reference log:: - - >>> head = repo.lookup_reference('refs/heads/master') - >>> for entry in head.log(): - ... print(entry.message) - -The interface for RefLogEntry:: - - RefLogEntry.committer -- Signature of Committer - RefLogEntry.message -- the message of the RefLogEntry - RefLogEntry.oid_old -- oid of old reference - RefLogEntry.oid_new -- oid of new reference - -Revision parsing -================ - -You can use any of the fancy `` forms supported by libgit2:: - - >>> commit = repo.revparse_single('HEAD^') - -Revision walking -================= - -You can iterate through the revision history with repo.walk:: - - >>> from pygit2 import GIT_SORT_TIME - >>> for commit in repo.walk(oid, GIT_SORT_TIME): - ... print(commit.hex) - -The 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 - -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 diff --git a/docs/references.rst b/docs/references.rst new file mode 100644 index 0000000..d56ec70 --- /dev/null +++ b/docs/references.rst @@ -0,0 +1,22 @@ +********************************************************************** +References +********************************************************************** + +Reference lookup:: + + >>> all_refs = repo.listall_references() + >>> master_ref = repo.lookup_reference("refs/heads/master") + >>> commit = repo[master_ref.oid] + +Reference log:: + + >>> head = repo.lookup_reference('refs/heads/master') + >>> for entry in head.log(): + ... print(entry.message) + +The interface for RefLogEntry:: + + RefLogEntry.committer -- Signature of Committer + RefLogEntry.message -- the message of the RefLogEntry + RefLogEntry.oid_old -- oid of old reference + RefLogEntry.oid_new -- oid of new reference diff --git a/docs/repository.rst b/docs/repository.rst new file mode 100644 index 0000000..551717f --- /dev/null +++ b/docs/repository.rst @@ -0,0 +1,24 @@ +********************************************************************** +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) + + + +These are the basic attributes of a repository:: + + Repository.path -- path to the Git repository + Repository.workdir -- path to the working directory, None in the case of + a bare repo diff --git a/docs/revparse.rst b/docs/revparse.rst new file mode 100644 index 0000000..42c11a5 --- /dev/null +++ b/docs/revparse.rst @@ -0,0 +1,7 @@ +********************************************************************** +Revision parsing +********************************************************************** + +You can use any of the fancy `` forms supported by libgit2:: + + >>> commit = repo.revparse_single('HEAD^') diff --git a/docs/status.rst b/docs/status.rst new file mode 100644 index 0000000..6bfdbfc --- /dev/null +++ b/docs/status.rst @@ -0,0 +1,11 @@ +********************************************************************** +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