Documentation Instructions

For writing guide please generate and review docguide. Documentation is written in a combination of:

• sphinx-doc.org: user manual, developers guide and documentation guide
• swagger.io - REST API reference documentation

GeoServer documentation is released using Creative Commons Attribution 4.0 International.

Python and Sphinx Setup

The documentation is written with sphinx-build, 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
sphinx-autobuild --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
sphinx-autobuild --version

Building with Maven

To build:

mvn clean install

index.html

The file index.html is the landing page for the online documentation. It exists outside of the version hierarchy of the rest of the documentation.

REST API

To generate the REST API documentation:

mvn process-resources

To generate a specific REST API endpoint:

mvn process-resources:system-status

Manuals

To build all restructured text documentation:

mvn compile

And to package into zips:

mvn package

Profiles are defined to build individual manuals:

mvn compile -Puser
mvn compile -Pdeveloper
mvn compile -Pdocguide

And can be packaged individually:

mvn package:single@user
mvn package:single@developer
mvn package:single@docguide

To generate user pdf:

mvn compile -Puser-pdf

Writing

The ant build.xml can also be called directly:

ant user

This uses sphinx-build to generate documentation into target/user/html/index.html.

To view content while editing:

ant user-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.

Additional targets are available:

ant developer
ant developer-site
ant docguide
ant docguide-site

Customize output with current project.version name:

ant user -Dproject.version=2.23.1