Permalink
Browse files

Documentation restructuring. Docs now hosted on ReadTheDocs, with the…

… README being more of just that, a README.
  • Loading branch information...
1 parent c1ff64d commit 0e63c946fb00922e5806c96872caa3c9ea136302 @magnusnordlander magnusnordlander committed Apr 18, 2012
View
@@ -1,4 +1,5 @@
.DS_Store
*.sublime-*
vendor
-composer.lock
+composer.lock
+docs/_build
View
126 README.md
@@ -1,7 +1,9 @@
# Gittern
Making Git like music for PHP's ears. [![Build Status](https://secure.travis-ci.org/e-butik/Gittern.png)](http://travis-ci.org/e-butik/Gittern)
-Version 0.8 (because starting out at 0.1 or 1.0 is for squares)
+Version 0.8 under development (because starting out at 0.1 or 1.0 is for squares)
+
+Documentation is available at [Read the Docs](http://gittern.readthedocs.org/).
## What is Gittern?
Gittern is a PHP library for reading from and writing to Git repositories. It doesn't depend on the ```git``` binary, it directly acccesses the repo files.
@@ -18,92 +20,10 @@ In addition to all of this functionality, Gittern is created with extensibility
E-butik.se, one of Sweden's foremost e-commerce platform providers. Visit our [developer blog](http://developer.e-butik.se).
## How do I install Gittern?
-Use [Composer](http://getcomposer.org/).
-
-## How do I use Gittern?
-There's basically three ways.
-
-### Part the first, the GitternCommitishReadOnlyAdapter
-Code speaks louder than words:
-
-```php
-use Gittern\Repository,
- Gittern\Transport\NativeTransport,
- Gittern\Configurator,
- Gittern\Gaufrette\GitternCommitishReadOnlyAdapter;
-
-use Gaufrette\Filesystem;
-
-$repo = new Repository;
-$repo->setTransport(new NativeTransport($repo_path));
-
-$configurator = new Configurator;
-$configurator->defaultConfigure($repo);
-
-$filesystem = new Filesystem(new GitternCommitishReadOnlyAdapter($repo, "master"));
-```
-
-After this, you can use the filesystem like any other Gaufrette Filesystem. Just bear in mind that it's read-only, and will throw exceptions if you try to modify it.
-
-### Part the second, the GitternIndexAdapter
-
-Again, code speaks louder than words:
-
-```php
-use Gittern\Repository,
- Gittern\Transport\NativeTransport,
- Gittern\Configurator,
- Gittern\Gaufrette\GitternIndexAdapter;
-
-use Gaufrette\Filesystem;
-
-$repo = new Repository;
-$repo->setTransport(new NativeTransport($repo_path));
-
-$configurator = new Configurator;
-$configurator->defaultConfigure($repo);
-
-$filesystem = new Filesystem(new GitternIndexAdapter($repo));
-```
-
-After this, you can use the filesystem like any other Gaufrette Filesystem.
-
-#### Committing
-The Git Index contains everything necessary to create a tree. Once you have a tree, creating a commit is a fairly straight-forward deal, but additional convenience is under consideration.
-
-```php
-use Gittern\Entity\GitObject\Commit,
- Gittern\Entity\GitObject\User;
-
-use DateTime;
-
-$parent = $repo->getObject('master');
-
-$tree = $repo->getIndex()->createTree();
-$commit = new Commit;
-$commit->setTree($tree);
-$commit->addParent($parent);
-$commit->setMessage("Added another file");
-$commit->setAuthor(new User("Tessie Testson", "tessie.testson@example.com"));
-$commit->setCommitter(new User("Tessie Testson", "tessie.testson@example.com"));
-$commit->setAuthorTime(new DateTime);
-$commit->setCommitTime(new DateTime);
+Use [Composer](http://getcomposer.org/). More detailed instructions are available in the docs.
-$repo->desiccateGitObject($commit);
-$repo->setBranch('master', $commit);
-
-$repo->flush();
-```
-
-### Part the third, the low level interface
-**This section is very much incomplete. Currently, take a look at the test suite and the code to gain insight into how Gittern works.**
-
-The low level interface is where the magic happens. This is also where you'll absolutely need to be familiar with the git model of blobs, trees, commits, and how the fit together. Seriously. If you don't e.g. know what a tree is (in the context of git, of course), probably won't understand how to use this, and theoretically you might be able to break your repos when using the low level interface. Proceed with caution.
-
-If you want to learn how git works, there's plenty of resources. I'd suggest the following, in order:
-
-* [Think like (a) Git](http://think-like-a-git.net/)
-* The Internals and Plumbing chapters in the [Git Community Book](http://book.git-scm.com/index.html)
+## How stable is the API?
+Not very. We're still refactoring the API pretty much whenever we feel like it. What is semi-stable though is that the Gaufrette adapters will remain compatible with the Gaufrette master branch, so if you're mainly using the Gaufrette adapters, you'll not experience a lot of API breakage.
## Kinda-sorta bugs
* The index flags field (see http://opensource.apple.com/source/Git/Git-26/src/git-htmldocs/technical/index-format.txt) contains an assume-valid flag that's not represented
@@ -123,36 +43,4 @@ There are several planned features, which didn't make it in to version 0.8.
* Support for the commit tree entry type (i.e. submodules)
* Making the Gittern\Entity\GitObject\User class into an interface
* Support for all kinds of [Git Treeishes](http://book.git-scm.com/4_git_treeishes.html)
-* Support for updating the reflog when moving a branch head
-
-## Technical docs - What does the different kind of classes do?
-
-### Entities
-
-The Git object model has quite a few entities, and Gittern divides them into two categories. GitObjects and "other". Any kind of entity which is persisted in the Git object store is a GitObject. That means Commits, trees (and their different node types), blobs and annotated tags (not yet supported). The index and it's entries are the current "other" entities.
-
-All of these objects represent a concept present in the Git object model.
-
-### Proxy
-
-When you fetch a Git entity (unless it's a blob), it's probably going to have relations to other entities. To make it easier to work with the objects, Gittern creates proxy objects for these relations. When a method requires data that the proxy object doesn't already have (pretty much anything but the SHA), the proxy lazily loads the data from the repository.
-
-Proxies are decorators of the class they're proxying, and thus will pass a type check.
-
-### Hydrator
-
-In a normal git repository, the files are stored according to a certain file specification. The role of the hydrator is to a RawObject (which is basically just the file data and it's sha), and create an entity from it.
-
-### Desiccator
-
-A de-hydrator. Where a hydrator takes a RawObject and creates an entity from it, the desiccator takes and entity and creates a RawObject from it.
-
-### Transport
-
-In order for Gittern to be modular, the Repository class doesn't actually know how to read and write your RawObjects et c. from/to the disk. Maybe you don't even care that much about keeping compatibility with the git binary, and want to store your objects somewhere else. Maybe you want to cache them in e.g. Redis.
-
-For this reason there's the Transport. The Transport knows all about how to get your objects from the disk, how to resolve references, et c.
-
-### Adapters
-
-Due to it's fine representation of the Git object model, Gittern is a breeze to work with. However, sometimes you don't actually care about the Git object model. Sometimes you just want to treat it like a filesystem. Lucky for us the fine folks at KnpLabs have created [Gaufrette](https://github.com/KnpLabs/Gaufrette), a file system abstraction layer. Gittern has two Gaufrette adapters, allowing you to treat a git repository like any other file system.
+* Support for updating the reflog when moving a branch head
View
@@ -0,0 +1,153 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Gittern.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Gittern.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/Gittern"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Gittern"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
Oops, something went wrong.

0 comments on commit 0e63c94

Please sign in to comment.