website/README.txt: Test and update instructions

Author: techtonik

website/README.txt

@@ -1,4 +1,14 @@
-issues.roundup-tracker.org:
+Roundup has three web sites:
+
+ * http://www.roundup-tracker.org/
+ * http://wiki.roundup-tracker.org/
+ * http://issues.roundup-tracker.org/
+
+www and wiki are hosted on SourceForge.
+
+
+updating issues.roundup-tracker.org
+===================================
 
  * log into issues.roundup-tracker.org
  * get a working copy of roundup/website/issues from the SCM, either via
@@ -16,47 +26,76 @@ issues.roundup-tracker.org:
  * restart the roundup server:
       sudo /etc/init.d/roundup restart
 
-[1] All services hosted on sf.net:
- * log into sf.net (Generic sf instructions can be found here:
-   http://sourceforge.net/apps/trac/sourceforge/wiki/Shell%20service )
-      ssh -t <user>,[email protected] create
- * set project_home:
-      project_home=/home/project-web/roundup
-      cd ${project_home}
- * read up on other people changes and add yours
-      vim ${project_home}/logbuch.txt
- * update the working copy of the SCM roundup source (includes www and wiki)
-      cd ${project_home}/src/roundup
-      hg pull -u
-   (The warning about "Not trusting file /home/hg/p/roundup/code/.hg/hgrc
-   from untrusted user" can be ignored.)
- * When done working in the shell, you can destroy it early to free resources:
-      shutdown
-
-www.roundup-tracker.org:
- * follow [1].
- * activate the virtualenv
-      . ${project_home}/docbuilder/bin/activate
- * go to the now current source directory
-      cd ${project_home}/src/roundup/website/www
- * (build requirement: sphinx and the sphinxcontrib-cheeseshop plugin
-      http://pypi.python.org/pypi/sphinxcontrib-cheeseshop)
- * build it
-      make html
- * you may also "make clean"
- * install it
-     cp -r ./html/* ${project_home}/htdocs/
-   or alternatively (leaving out the --dry-run later)
-     rsync --dry-run -v --checksum --recursive ./html/* ${project_home}/htdocs/
-
-(I think I can simplify the Makefile above such that the installation will be included as a make target.)
-
-wiki.roundup-tracker.org:
- * follow [1].
- * the main wiki configuration is here
-      vim persistent/wiki/wikiconfig.py
- * go to the now current source directory
-      cd ${project_home}/src/roundup/website/wiki
- * copy the files into the right places:
-      cp static/roundup/* ${project_home}/htdocs/_wiki/
-      cp wiki/data/plugin/theme/roundup.py ${project_home}/persistent/wiki/data/plugin/theme/
+
+updating services hosted on sf.net (www and wiki)
+=================================================
+Generic SF instructions for web service recommend
+uploading files through SFTP, described here:
+http://sourceforge.net/p/forge/documentation/Project%20Web%20Services/
+
+However, SFTP is ugly to script in non-interactive
+mode, so we use SSH access to fetch everything and
+build from server side.
+
+logging into sf.net
+-------------------
+Current docs are taken down with SourceForge Trac,
+so working instructions are available from here:
+http://web.archive.org/web/20140618231150/http://sourceforge.net/apps/trac/sourceforge/wiki/Shell%20service
+
+    # log in, replace <user> with your account
+    ssh -t <user>,[email protected] create
+
+    # set project_home and go there
+    project_home=/home/project-web/roundup
+    cd ${project_home}
+
+    # read up on other people changes and add yours
+    vim logbuch.txt
+
+    # pull latest Roundup source with www and wiki
+    # (the warning about "Not trusting file ... " can be ignored
+    #  for now https://sourceforge.net/p/forge/site-support/8217/)
+    hg pull -u --cwd src/roundup
+
+
+updating wiki.roundup-tracker.org
+---------------------------------
+wiki doesn't require building anything, so if you're
+logged in to SF (see above), just copy new files over
+to new directories:
+
+    cd ${project_home}/src/roundup/website/wiki
+    cp -r -p static/roundup ${project_home}/htdocs/_wiki/
+    cp -p wiki/data/plugin/theme/roundup.py ${project_home}/persistent/wiki/data/plugin/theme/
+    cd -
+
+If you need to adjust wiki configuration, it is here:
+
+    vim persistent/wiki/wikiconfig.py
+
+
+updating www.roundup-tracker.org
+---------------------------------
+Site update requires rebuilding HTML files. For that
+you `sphinx` and `sphinxcontrib-cheeseshop` are required/
+Hopefully, they are already installed into virtualenv, so
+the whole procedure looks like so:
+
+    # activate the virtualenv
+    . ${project_home}/docbuilder/bin/activate
+    # cd to website source and build it
+    cd ${project_home}/src/roundup/website/www
+    make clean
+    make html
+    # you can check which files updated
+    #diff -qur ./html/ ${project_home}/htdocs/
+    # copy to website dir
+    cp -r -p ./html/* ${project_home}/htdocs/
+    # or try it with rsync (skip --dry-run when ready)
+    #rsync --dry-run -v --checksum --recursive ./html/* ${project_home}/htdocs/
+
+When done working in the shell, you can destroy it early
+to free resources:
+
+    shutdown