[RFC] Migrated to Sphinx

Makefile

@@ -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/PHPCR.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PHPCR.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/PHPCR"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PHPCR"
+	@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."

README.md

@@ -1,3 +1,6 @@
 Documentation for the PHP Content Repository PHPCR
 
-This repository contains the source files. Please visit [phpcr.github.com](http://phpcr.github.com) for a user friendly access to the documentation on PHPCR.
+This repository contains the source files. The documentation is hosted on
+readthedocs.org: http://phpcr.readthedocs.org/en/latest/
+
+You can also visit the official PHPCR website: phpcr.github.io

_theme/phpcr/layout.html

@@ -0,0 +1,17 @@
+{% extends "pyramid/layout.html" %}
+{% block extrahead %}
+    <link rel="stylesheet" href="{{ pathto('_static/phpcr.css', 1) }}" type="text/css" />
+{% endblock %}
+
+{% block header %}
+{%- if logo %}
+<div class="header">
+  <a href="https://phpcr.github.io">&laquo;  Back to PHPCR website</a>
+  <div class="logo">
+      <a href="https://phpcr.github.io"><img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/></a>
+    </a>
+  </div>
+  <div style="clear: both"></div>
+</div>
+{%- endif %}
+{% endblock %}

_theme/phpcr/static/phpcr.css

@@ -0,0 +1,22 @@
+div.header {.
+     margin: 0;
+     background: #191818;
+     background-image: none;
+     color: #333;
+     text-align: left;
+     padding: 10px 10px 10px 10px;
+     border-bottom: 1px solid #eee;
+ }
+
+div.logo {
+    text-align: left;
+    padding-top: 0px;
+}
+
+div.header a {
+    color: white;
+}
+
+div.header .logo {
+    float: right;
+}

_theme/phpcr/theme.conf

@@ -0,0 +1,4 @@
+[theme]
+inherit = pyramid
+stylesheet = pyramid.css
+pygments_style = sphinx

book/conclusion.rst

@@ -0,0 +1,12 @@
+Conclusion and further reading
+==============================
+
+We hope this guide helps to get you started. If you miss anything, have suggestions or questions, please contact us on jackalope-dev@googlegroups.com or #jackalope on irc.freenode.net
+
+Further reading
+---------------
+
+Browse through the [API documentation](http://phpcr.github.com/doc/html/index.html) to see what each of the core elements mentioned in the introduction can do.
+
+To fully understand the concepts behind the content repository API, we suggest reading [the Java content repository specification](http://www.day.com/specs/jcr/2.0/index.html) and
+then the [simplifications we did for PHP](https://github.com/phpcr/phpcr/blob/master/doc/JCR_TO_PHPCR.txt).

book/getting_started.rst

@@ -0,0 +1,108 @@
+Getting Stated
+==============
+
+This aims to provide a rounded general reference to PHPCR. You will mostly see
+code examples. It should work with any PHPCR implementation. We propose using
+`Jackalope Jackrabbit <https://github.com/jackalope/jackalope-jackrabbit>`_ to
+get started as it supports all features described here.
+
+Installing Jackalope
+--------------------
+
+Just follow the README of the
+`jackalope-jackrabbit <https://github.com/jackalope/jackalope-jackrabbit/blob/master/README.md>`_
+repository.
+
+Browser to see what is in the repository
+----------------------------------------
+
+There are currently two options for browsing and modifying the contents of the
+PHPCR repository.
+
+- `PHPCR Shell <https://github.com/phpcr/phpcr-shell>`_: Aims to provide a full
+  command line shell interface to PHPCR content repositories. A pre-compiled
+  PHAR archive is available on the github homepage. 
+
+- `Marmelab PHPCR Browser <https://github.com/marmelab/phpcr-browser>`_:
+  A user-friendly web based PHPCR browser.
+
+The shell is currently more feature complete, but the PHPCR Browser is more
+user friendly. We suggest you try both.
+
+In a nutshell
+-------------
+
+The shortest self-contained example should output a line with 'value':
+
+.. code-block:: php
+
+    <?php
+    require('/path/to/jackalope-jackrabbit/vendor/autoload.php');
+
+    $factoryclass = '\Jackalope\RepositoryFactoryJackrabbit';
+    $parameters = array('jackalope.jackrabbit_uri' => 'http://localhost:8080/server');
+
+    // end of implementation specific configuration
+
+    // get a new PHPCR repository instance from the factory class defined above
+    $factory = new $factoryclass();
+    $repository = $factory->getRepository($parameters);
+
+    // create the credentials object to authenticate with the repository
+    $credentials = new \PHPCR\SimpleCredentials('admin','admin');
+
+    // login to the repository and retrieve the session
+    $session = $repository->login($credentials, 'default');
+
+    // retrieve the root node of the repository ("/")
+    $root = $session->getRootNode();
+
+    // add a new node
+    $node = $root->addNode('test', 'nt:unstructured');
+
+    // set a property on the newly created property
+    $node->setProperty('prop', 'value');
+
+    // save the session, i.e. persist the data
+    $session->save();
+
+    // retrieve the newly created node
+    $node = $session->getNode('/test');
+    echo $node->getPropertyValue('prop'); // outputs "value"
+
+
+Still with us? Good, lets get in a bit deeper...
+
+Get some data into the repository
+---------------------------------
+
+We will discuss the import feature in more detail later, but to have some
+data, we just import something here. Create an XML file called `test.xml``:
+
+.. code-block:: xml
+
+    <data xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0">
+        <node title="Test" content="This is some test content" />
+        <sibling title="Test" content="This is another test content">
+            <child1 title="Child1 title" />
+            <child2 title="Child2 title" />
+            <otherchild title="Otherchild title"/>
+            <yetanother title="Yetanother title">
+                <child title="Child title" />
+            </yetanother>
+        </sibling>
+    </data>
+
+Now import this into the repository:
+
+.. code-block:: php
+
+    <?php
+    $session->importXML('/', 'test.xml', \PHPCR\ImportUUIDBehaviorInterface::IMPORT_UUID_CREATE_NEW);
+    $session->save();
+
+You may also use the PHPCR Shell to import data:
+
+.. code-block:: bash
+
+   phpcrsh -pmyprofile -c "session:import-xml test.xml"

book/import_export.rst

@@ -0,0 +1,67 @@
+Import and export data
+======================
+
+As promised, here are some more details on importing and exporting data. There
+are two formats:
+
+* The *document view* translates the data into a XML document with node names
+    as xml elements and properties as attributes and thus very readable. Type
+    information is lost, and illegal XML characters are encoded.
+* The *system view* is a more strict XML document defining the exact structure
+    of the repository with all type information. However, it is more verbose.
+
+As an analogy, think about an SQL dump file with SQL statements and the dump of
+an SQL table into a ``csv`` file. You can restore the data from both, but the SQL
+dump knows every detail about your field types and so on while the CSV just
+knows the data.
+
+When exporting, you explictly call a method corresponding to the desired
+format:
+
+.. code-block:: php
+
+    <?php
+    $file = fopen('/tmp/document.xml', 'w+');
+
+    // dump the tree at /foo/bar into a document view file
+    $session->exportDocumentView(
+        '/data/sibling',
+        $file,
+        true, // skip binary properties to not have large files in the dump
+        false // recursivly output the child nodes as well
+    );
+
+    fclose($file);
+
+    $file = fopen('/tmp/system.xml', 'w+');
+    // export the tree at /foo/bar into a system view xml file
+    $session->exportSystemView(
+        '/data/sibling',
+        $file,
+        false, // do not skip binary properties
+        false
+    );
+
+    fclose($file);
+
+Importing detects the format automatically. If the document is a valid JCR
+system view, it is interpreted according to that format, otherwise if it is a
+valid XML document it is imported as document:
+
+.. code-block:: php
+
+    <?php
+    $filename = 'dump.xml';
+    $session->getRootNode()->addNode('imported_data', 'nt:unstructured');
+    $session->importXML(
+        '/imported_data', // attach the imported data at this node
+        $filename,
+        ImportUUIDBehaviorInterface::IMPORT_UUID_CREATE_NEW
+    );
+
+When importing nodes with a uuid, a couple of different behaviors can be used:
+
+* ``IMPORT_UUID_CREATE_NEW``: Create new UUIDs for nodes that are imported, so you never get collisions.
+* ``IMPORT_UUID_COLLISION_THROW``: Throw an exception if a node with the same UUID already exists.
+* ``IMPORT_UUID_COLLISION_REMOVE_EXISTING``: Remove an existing node if an imported node has the same UUID.
+* ``IMPORT_UUID_COLLISION_REPLACE_EXISTING``: Replace existing node with the imported node. This can lead to the imported data being put in various places.