documentation build updates

Makefile

@@ -4,10 +4,10 @@
 # You can set these variables from the command line.
 SPHINXBINS    = .tox/docs/bin
 SRCDIR        = source
-SPHINXOPTS    = #-W
+SPHINXOPTS    = # used by html_languages to specify $$lang
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
+BUILDDIR      = target
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -17,15 +17,21 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR) -j auto --no-color -q
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
+	@echo "  clean"
+	@echo "  html                to make standalone HTML files"
+	@echo "  html_all_languages  build html documentation for all languages "
+	@echo "  html_languages      build html docs for LANGS environmental variable"
+	@echo "  html_eng            build html documentation for english"
+	@echo "  update_translations Pushing strings to transifex"
+	@echo "Along with traditional sphinx targets:"
 	@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"

README.md

@@ -1,26 +1,66 @@
 # Project documentation module
 
-Check the ["Writing documentation" guide](https://geonetwork-opensource.org/manuals/3.8.x/en/contributing/writing-documentation.html).
+Documentation for GeoNetwork Opensource available via https://geonetwork-opensource.org.
+This manual is included in each build in the `docs` folder as a git submodule.
+
+This documentation is supports open access using a [Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0)](LICENSE.md).
 
+![GeoNetwork Logo](source/_static/GN3.png "GeoNetwork")
+
+# Writing Guide
+
+Check the ["Writing documentation" guide](https://geonetwork-opensource.org/manuals/3.8.x/en/contributing/writing-documentation.html).
 
 # Build
 
-The `latest` maven profile updates the translations from Transifex.
+To quickly build the english docs:
 
-Documentation for all languages:
+```
+make html_eng
+```
+
+A build of the documentation (defaulting to English and French):
 
 ```
-mvn package -Pall,latest
+mvn package
 ```
 
-Documentation for English and French:
+The `latest` maven profile updates the translations from Transifex (this will take some time).
+
+```
+mvn generate-resources -Platest
+```
 
+These can be be used together:
 ```
 mvn package -Platest
 ```
 
+To use all languages:
+
+```
+mvn package -Platest -Pall
+```
+
 A subset of languages (for example: English, French and Spanish):
 
 ```
-mvn package -Platest -Dlangs='"en" "fr" "es"'
-```
+mvn package -Platest -Dlangs='"en" "fr" "es"' -Dtranslations='en,fr,es'
+```
+
+# Before you start
+
+The maven build above makes use of the transifex command line client `tx`: 
+
+* https://docs.transifex.com/client/introduction
+
+Prior to use you will need to generate and API key:
+
+* https://www.transifex.com/user/settings/api/
+
+If you have never used `tx` before you will need to run it once interactively to install the API key:
+
+```
+tx pull --language='fr'
+[?] Enter your api token:
+```