diff --git a/doc/.gitignore b/doc/.gitignore index 164f6c7f..8637e23d 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,5 +1,6 @@ _build _upload _test +_spelling _static/img/gen .sconsign.dblite diff --git a/doc/Makefile b/doc/Makefile index 766be391..76500306 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,3 +1,16 @@ +all: + @echo "Targets:" + @echo "" + @echo " clean : cleanup build artifacts" + @echo " test : build everything and run locally" + @echo " test_no_network : build everything for no network access and run locally" + @echo " publish : build everything and publish to S3" + @echo " copy : copy over shared files to other AutobahnXXX repos" + @echo " install_deps : install build dependencies" + @echo " spelling : run spell checking" + @echo " doctest : run doctests" + @echo "" + build: scons @@ -35,7 +48,25 @@ copy_makefile: cp Makefile ../../AutobahnCpp/doc/ cp Makefile ../../AutobahnTestsuite/doc/ -copy: copy_css copy_makefile +copy_gitignore: + cp .gitignore ../../AutobahnJS/doc/ + cp .gitignore ../../AutobahnAndroid/doc/ + cp .gitignore ../../AutobahnCpp/doc/ + cp .gitignore ../../AutobahnTestsuite/doc/ + +copy_serve: + cp serve.py ../../AutobahnJS/doc/ + cp serve.py ../../AutobahnAndroid/doc/ + cp serve.py ../../AutobahnCpp/doc/ + cp serve.py ../../AutobahnTestsuite/doc/ + +copy_readme: + cp README.md ../../AutobahnJS/doc/ + cp README.md ../../AutobahnAndroid/doc/ + cp README.md ../../AutobahnCpp/doc/ + cp README.md ../../AutobahnTestsuite/doc/ + +copy: copy_css copy_makefile copy_gitignore copy_serve install_deps: pip install -U scour diff --git a/doc/README.md b/doc/README.md index 1686ff05..b660e8b3 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,61 +1,17 @@ # Documentation -The **Autobahn**|Python documentation is generated using [Sphinx](http://sphinx.pocoo.org/) and the generated documentation is hosted [here](http://autobahn.ws/python). +The documentation is generated using [Sphinx](http://sphinx.pocoo.org/) and the generated documentation is hosted [here](http://autobahn.ws/) under the language specific subsite. +## Prerequisites -## Generate - -You will need to have [SCons](http://scons.org/) installed, plus the following +You will need to have Python and [SCons](http://www.scons.org/) installed. To install the rest of the build dependencies ```sh -pip install taschenmesser -pip install sphinx -pip install sphinx-bootstrap-theme -pip install sphinxcontrib-spelling -pip install repoze.sphinx.autointerface +make install_deps ``` -To generate the documentation +Then, to get help on available build targets, just type ```sh -cd doc -scons +make ``` - -This will create the documentation under the directory `_build`. - - -## 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. diff --git a/doc/SConstruct b/doc/SConstruct index acd29cf1..b45339a5 100644 --- a/doc/SConstruct +++ b/doc/SConstruct @@ -94,13 +94,3 @@ Depends(uploaded, imgs) Clean(uploaded, UPLOADED) 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 =( -#test = env.Command(None, [imgs, docs], 'python serve.py --root ./_build --silence') - -#env.AlwaysBuild(test) -#Alias("test", test) diff --git a/doc/conf.py b/doc/conf.py index 008360d0..4abf0fda 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -188,20 +188,10 @@ no_network = None # Custom sidebar templates, maps document names to template names. html_sidebars = { 'index': [ - 'side-primary.html', - #'side-secondary.html', - #'stay_informed.html', - #'sidetoc.html', - #'previous_next.html', - #'searchbox.html' + 'side-primary.html' ], '**': [ - 'side-primary.html', - # 'side-secondary.html', - #'stay_informed.html', - # 'sidetoc.html', - #'previous_next.html', - #'searchbox.html' + 'side-primary.html' ] }