documentation build, site and package (#1116)

* ant docs - for sphinx-build html doc generation
* Ignore macOS .DS_Store files
* ant package - for zip of generated docs
* ant site - for sphinx-autobuild live preview

.gitignore

@@ -5,9 +5,13 @@ bin
 target
 .DS_Store
 release.rb
+
 # Intellij
 .idea/
 *.iml
+
 # spotless up to date checks
 .spotless-index
 
+# os specific files
+.DS_Store

documentation/en/.gitignore

@@ -0,0 +1 @@
+venv

documentation/en/README.md

@@ -0,0 +1,93 @@
+# GeoWebCache Documentation
+
+GeoWebCache documentation:
+
+* ``user/`` documentation files
+* ``user/source/config.py`` - documentation build settings
+* ``user/source/index.rst`` - first page of documentation 
+* ``target/user/html/`` - build output 
+* ``target/user/html/index.html`` - first page of generated html
+
+## Ant Build
+
+An ant ``build.xml`` script provided (note the python environment described below is required).
+
+To generate html documentation:
+
+```
+ant docs
+```
+
+This uses ``sphinx-build`` to generate documentation into: ``target/user/html/index.html``
+
+To view content while editing:
+
+```
+ant site
+```
+
+This uses ``sphinx-autobuild`` to serve docs on next available port, opening a browser to review generated pages. The browser will refresh as pages are edited and saved.
+
+To package documentation bundle:
+```
+ant package
+```
+
+Contents are packaged into: ``target/geowebcache_1.23-SNAPSHOT-docs.zip``
+
+## Make Build
+
+A ``Makefile`` and ``make.bat`` file is provided:
+```
+cd user
+make html
+```
+
+Contents are generated into:
+```
+open build/html/index.html
+```
+
+## Python and Sphinx Setup
+
+The documentation is written with [sphinx-build](https://www.sphinx-doc.org/en/master/), which is a Python documentation generator.
+
+Install Python (macOS example):
+```
+brew install python
+```
+
+To install ``sphinx-build`` and ``sphinx-autobuild`` using ``requirements.txt``:
+```
+pip3 install -r requirements.txt
+```
+
+To confirm installation:
+```
+sphinx-build --version
+```
+
+## Python Virtual Environment Setup
+
+Optional: To establish a virtual environment just for this project (macOS example):
+
+```
+brew install virtualenv
+virtualenv venv
+```
+
+To activate python:
+```
+source venv/bin/activate
+```
+
+To install requirements into virtual environment:
+```
+pip install -r requirements.txt
+```
+
+To confirm installation:
+```
+sphinx-build --version
+```
+

documentation/en/build.xml

@@ -0,0 +1,101 @@
+<project name="geowebcache-docs" default="docs"
+  xmlns:if="ant:if"
+  xmlns:unless="ant:unless"
+>
+
+  <property name="build.directory" value="${basedir}/target"/>
+
+  <property environment="env"/>
+
+  <condition property="sphinx.available">
+    <or>
+      <available file="sphinx-build" filepath="${env.PATH}"/>
+      <available file="sphinx-build.exe" filepath="${env.Path}"/>
+      <available file="sphinx-build.exe" filepath="${env.PATH}"/>
+    </or>
+  </condition>
+
+  <condition property="autobuild.available">
+    <or>
+      <available file="sphinx-autobuild" filepath="${env.PATH}"/>
+      <available file="sphinx-autobuild.exe" filepath="${env.Path}"/>
+      <available file="sphinx-autobuild.exe" filepath="${env.PATH}"/>
+    </or>
+  </condition>
+
+  <loadfile
+    encoding="UTF-8"
+    property="project.version"
+    srcFile="../../geowebcache/pom.xml" >
+    <filterchain>
+      <tokenfilter>
+        <containsregex pattern="^\s*&lt;version&gt;(\S*)&lt;/version&gt;$" replace="\1" />
+      </tokenfilter>
+      <filterreader classname="org.apache.tools.ant.filters.HeadFilter">
+        <param name="lines" value="1"/>
+      </filterreader>
+      <striplinebreaks/>
+    </filterchain>
+  </loadfile>
+
+  <target name="clean"
+    description="Clear target/html documentation">
+    <delete includeemptydirs="true" failonerror="false">
+      <fileset dir="${build.directory}" defaultexcludes="false">
+        <include name="**/" />
+      </fileset>
+    </delete>
+  </target>
+
+  <target name="docs"
+    description="Generate html documentation">
+
+    <mkdir dir="${build.directory}"/>
+    <antcall target="sphinx">
+      <param name="id" value="user" />
+    </antcall>
+    <property name="file" value="${build.directory}/user/html/index.html"/>
+    <available file="${file}" type="file" property="file.present"/>
+    <echo level="info" if:set="file.present">File generated ${file}</echo>
+    <echo level="error" unless:set="file.present">File not generated ${file}</echo>
+  </target>
+
+  <target name="package" depends="docs"
+    description="Generate zip documentation">
+    <echo>Generating geowebcache_${project.version}-docs.zip</echo>
+    <zip destfile="${build.directory}/geowebcache_${project.version}-docs.zip"
+         level="0"
+         basedir="${build.directory}/user/html"
+         includes="**"
+         excludes="**/.gitignore, .DS_Store"/>
+  </target>
+
+  <target name="site"
+    description="Generate html documentation">
+
+    <mkdir dir="${build.directory}"/>
+    <antcall target="autobuild">
+      <param name="id" value="user" />
+    </antcall>
+  </target>
+
+  <target name="sphinx" if="sphinx.available">
+    <local name="argLine"/>
+    <property name="argLine" value="-D release=${project.version} -q -W --keep-going -b html -d &quot;${build.directory}/user/doctrees&quot; . &quot;${build.directory}/user/html&quot;"/>
+    <echo message="Running sphinx-build ${argLine}"/> 
+    <exec executable="sphinx-build" failonerror="true" dir="${basedir}/user/source">
+      <arg line="${argLine}"/>
+    </exec>
+  </target>
+
+
+  <target name="autobuild" if="autobuild.available">
+    <local name="argLine"/>
+    <property name="argLine" value="-D release=${project.version} -q -W -b html -d &quot;${build.directory}/user/doctrees&quot; . &quot;${build.directory}/user/html&quot;"/>
+    <echo message="Running sphinx-autobuild ${argLine}"/> 
+    <exec executable="sphinx-autobuild" failonerror="true" dir="${basedir}/user/source">
+      <arg line="${argLine} --open-browser"/>
+    </exec>
+  </target>
+
+</project>

documentation/en/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+sphinx-autobuild