DOC/ENH: migrate commit-doc-tree description from README.md to Sphinx

README.md

@@ -58,60 +58,5 @@ Commits should be marked. Declare both functionality and area.
 
 ## Website
 
-We use a combination of [Sphinx](http://sphinx.pocoo.org/) and
-[github-pages](http://pages.github.com/) to host the project website:
-[http://debilski.github.com/pelita/](http://debilski.github.com/pelita/).
 
-This means the sphinx generated content is keept in a seperate branch in the
-source code repository `gh-pages`. This branch has its own root commit and is
-hence disconnected from the commits that track the project code and also the
-documentation source code.
-
-#### To regenerate the project website (automatic):
-
-Use the [commit-doc.sh script](https://github.com/Debilski/pelita/blob/develop/commit-doc.sh).
-This will automatically make the commit of the latest version of the
-documentation on the `gh-pages` branch. After checking that everything is in
-order you still need to push that branch. Although the script tries
-very hard to not delete untracked files, you should be aware that any untracked
-files in the `doc` subdirectory will be *automatically deleted without warning*!
-
-#### To regenerate the project website (manual):
-
-Move to the `doc` directory:
-
-    $ cd doc
-
-Edit the documentation:
-
-    $ vim source/<file>.rst
-
-Generate html
-
-    $ make html
-
-Switch to the documentation branch:
-
-    $ git checkout gh-pages
-
-Move back up to the root directory:
-
-    $ cd ..
-
-Copy the generate documentation here:
-
-    $ cp -r doc/build/html/* .
-
-Add all tracked files that have been changed:
-
-    $ git add -u
-
-Add possibly new files:
-
-    $ git add <new pages>.html
-
-Make a commit message where `XXXXXXX` is the SHA-1
-prefix of the commit the documentation was # generated from:
-
-    $ git commit -m "sphinx generated doc from XXXXXXX"
 

commit-doc-tree.sh

@@ -1,7 +1,8 @@
 #!/bin/zsh
 
 # Script to automatically generate documentation and commit this to the gh-pages
-# branch. See README.md for more info about website maintenance and updates.
+# branch. See http://debilski.github.com/pelita/development.rst for more
+# information.
 
 # check, if index is empty
 if ! git diff-index --cached --quiet --ignore-submodules HEAD ; then

doc/source/development.rst

@@ -14,6 +14,79 @@ You can create a clone with::
 
     $ git clone git://github.com/Debilski/pelita.git
 
+
+Project Website
+===============
+
+We use the `Sphinx Tool <http://sphinx.pocoo.org/>`_ to generate the project
+website and `GitHub pages <http://pages.github.com/>`_ to host it.
+
+This means the sphinx generated content is kept in a separate branch in the
+source code repository called ``gh-pages`` (`gh-pages branch for Pelita
+<https://github.com/Debilski/pelita/commits/gh-pages>`_). This branch has its
+own root commit and is hence disconnected from the commits that track the
+project code and also the documentation source code.
+
+When this branch is pushed to GitHub the contained documentation is
+automatically deployed to the webserver. There are two ways to make commits to
+the ``gh-pages`` branch, using a script or with a series of manual git commands.
+Initially we used the manual commands, these were then converted into a script,
+which was subsequently upgraded multiple times. Hence the manual commands and
+the script are completely out of sync. The command listing is hence only
+provided to understand the process and **all website updates should be performed
+using the script**.
+
+Automatic
+---------
+
+Use the `commit-tree-doc.sh script
+<https://github.com/Debilski/pelita/blob/develop/commit-doc-tree.sh>`_.  This
+will automatically make the commit of the latest version of the documentation on
+the ``gh-pages`` branch. After checking that everything is in order you still need
+to push that branch.
+
+
+Manual
+------
+
+Move to the ``doc`` directory::
+
+    $ cd doc
+
+Edit the documentation::
+
+    $ vim source/<file>.rst
+
+Generate html::
+
+    $ make html
+
+Switch to the documentation branch::
+
+    $ git checkout gh-pages
+
+Move back up to the root directory::
+
+    $ cd ..
+
+Copy the generate documentation here::
+
+    $ cp -r doc/build/html/* .
+
+Add all tracked files that have been changed::
+
+    $ git add -u
+
+Add possibly new files::
+
+    $ git add <new pages>.html
+
+Make a commit message where ``XXXXXXX`` is the SHA-1
+prefix of the commit the documentation was # generated from::
+
+    $ git commit -m "sphinx generated doc from XXXXXXX"
+
+
 Project-Wall
 ============