doc structure cleanup

doc/.gitignore

@@ -1,4 +1,5 @@
-_gen
 _build
-*.pyc
+_gen
+_upload
+_static/img/gen
 .sconsign.dblite

doc/README.md

@@ -1,22 +1,61 @@
-**Autobahn**|Android documentation is generated using [Sphinx](http://sphinx-doc.org/).
+# Documentation
 
-To install Sphinx:
+The **Autobahn**|Android documentation is generated using [Sphinx](http://sphinx.pocoo.org/) and the generated documentation is hosted [here](http://autobahn.ws/android).
 
-	pip install -U sphinx
 
-To install [javasphinx](http://bronto.github.io/javasphinx/), install [lxml](https://pypi.python.org/pypi/lxml/) and then:
-
-	pip install -U javasphinx
+## Generate
 
-> Note: Due to a little bug, you currently need to use [this](https://github.com/oberstet/javasphinx).
+You will need to have [SCons](http://scons.org/) installed, plus the following
 
-To generate the docs:
+```sh
+pip install taschenmesser
+pip install sphinx
+pip install sphinx-bootstrap-theme
+pip install sphinxcontrib-spelling
+pip install repoze.sphinx.autointerface
+```
 
-	make html
+To generate the documentation
 
-> This will run `javasphinx-apidoc -u -o _gen ../Autobahn/src/` under the hood to first generate RST files from Javadoc.
-> 
+```sh
+cd doc
+scons
+```
 
-To cleanup
+This will create the documentation under the directory `_build`.
 
-	make clean
+
+## Test
+
+To build the documentation and start a Web server
+```sh
+scons test
+```
+
+## Clean
+
+To clean up all build artifacts
+
+```sh
+scons -uc
+```
+
+## Publish
+
+> Note: this section is only relevant for administrators of the [Autobahn web site](http://autobahn.ws/).
+
+Publishing requires a **2 step process**.
+
+**First** do
+
+```sh
+scons
+```
+
+to build the docs and **second** do
+
+```sh
+scons publish
+```
+
+to actually publish the docs.

doc/SConstruct

@@ -16,60 +16,78 @@
 ##
 ###############################################################################
 
+## Image file names to process
+SVG_FILES = [
+   "autobahnandroid.svg"
+]
+
+## Directory with image files to process
+IMG_SOURCE_DIR = "design"
+
+## Processed image files are placed here
+IMG_GEN_DIR    = "_static/img/gen"
+
+## Directory to upload
+DOCSDIR = '_build'
+
+## Contains fingerprints of uploaded files
+UPLOADED = '_build_uploaded'
+
+## The Tavendo S3 Bucket to upload to
+BUCKET = 'autobahn.ws'
+
+## The Bucket Prefix to upload files to
+BUCKET_PREFIX = 'android'
+
+### END OF CONFIG #############################################################
+
+
 import os
 import json
 import pkg_resources
 
+os.environ['PYTHONPATH'] = '../autobahn'
+
 taschenmesser = pkg_resources.resource_filename('taschenmesser', '..')
 #taschenmesser = "../../../infrequent/taschenmesser"
 env = Environment(tools = ['default', 'taschenmesser'],
                   toolpath = [taschenmesser],
                   ENV = os.environ)
 
-JAVADOCSDIR = '_gen'
-DOCSDIR = '_build'
-S3DIR = '_upload'
-
-##
-## Javasphinx Build
+## Process SVGs
 ##
-javadocs = env.Command(JAVADOCSDIR, [], "javasphinx-apidoc -u -o $TARGET ../Autobahn/src/")
-env.AlwaysBuild(javadocs)
-Clean(javadocs, JAVADOCSDIR)
+imgs = env.process_svg(SVG_FILES, IMG_SOURCE_DIR, IMG_GEN_DIR)
+
+Alias("img", imgs)
 
 
-##
 ## Sphinx Build
 ##
 docs = env.Command(DOCSDIR, [], "sphinx-build -b html . $TARGET")
+
 env.AlwaysBuild(docs)
 Clean(docs, DOCSDIR)
+Alias("doc", docs)
 
-Depends(docs, javadocs)
-Default(docs)
+Default([imgs, docs])
 
 
-##
 ## Upload to Amazon S3
 ##
-env['S3_RELPATH'] = DOCSDIR
-env['S3_BUCKET'] = 'autobahn.ws'
-env['S3_BUCKET_PREFIX'] = 'android/' # note the trailing slash!
-env['S3_OBJECT_ACL'] = 'public-read'
+uploaded = env.s3_dir_uploader(UPLOADED, DOCSDIR, BUCKET, BUCKET_PREFIX)
 
+Depends(uploaded, docs)
+Depends(uploaded, imgs)
 
-uploaded = []
-import fnmatch
-
-for root, dirnames, filenames in os.walk(DOCSDIR):
-   if not root.endswith('.doctrees'):
-      for filename in filenames:
-         if not fnmatch.fnmatch(filename, '*.s3'):
-            source = os.path.join(root, filename)
-            target = os.path.join(S3DIR, source)
-            uploaded.append(env.S3('{}.s3'.format(target), source))
+Clean(uploaded, UPLOADED)
 
-Depends(uploaded, docs)
-Clean(docs, S3DIR)
 Alias("publish", uploaded)
 
+
+## Run a test Web server
+##
+test = env.Command(None, [imgs, docs], 'twistd.py web -n -p 8080 --path="./_build/"')
+#test = env.Command(None, [imgs, docs], 'python -m SimpleHTTPServer 8080') # cannot set path here =(
+
+env.AlwaysBuild(test)
+Alias("test", test)

doc/_templates/layout.html

@@ -4,8 +4,8 @@
 
    {{ super() }}
 
-   <link rel="stylesheet" href="{{ pathto('_static/page.css', 1) }}">
-   <link rel="stylesheet" href="{{ pathto('_static/local.css', 1) }}">
+   <link rel="stylesheet" href="{{ pathto('_static/css/page.css', 1) }}">
+   <link rel="stylesheet" href="{{ pathto('_static/css/local.css', 1) }}">
 
    <script>
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
@@ -27,7 +27,7 @@
    <div class="extendedFooter">
       <div class="logoblock">
          <p class="logo">
-           <a href="{{ pathto('pages/index') }}"><img class="logo" src="{{ pathto('_static/logo.png', 1) }}" height="200" width="200" alt="Autobahn|Android"/></a>
+           <a href="{{ pathto('pages/index') }}"><img class="logo" src="{{ pathto('_static/img/logo.png', 1) }}" height="200" width="200" alt="Autobahn|Android"/></a>
          </p>
          <h3><strong>Autobahn</strong>|Android</h3>
          <p>