geocml / docs

User documentation for geoCML

geoCML documentation

This repository hosts the documentation for the geoCML project. geoCML documentation is rendered to HTML and PDF from Asciidoc files (.adoc) using docToolchain. docToolchain requires that you have Docker installed on your system, as builds are rendered inside of a container.

Writing new documentation topics

You may choose to extend the default geoCML documentation (distributed with all geoCML Base Deployments) as you customize your deployment. All Asciidoc topics are found in the project's topics/ directory. Simply add your new topics as a .adoc file to this directory and build using docToolchain's command line tool.

How to build your documentation

Requirements:

• asciidoctor
• asciidoctor-pdf
• asciidoctor-diagram

*nix / Bash:

Run ./gradlew generateHTML generatePDF

Windows:

Run "./gradlew.bat" generateHTML generatePDF

docs's Issues

Tradestudy of template languages

This issue is for capturing a trade study of the available template languages of interest for both user-facing & architecture documentation

Add documentation for Tabor constraint types

configure CI to build and publish docs

as to be able to view or download doc build artifacts (s.a., html or pdf documents)

'geoCML Task Scheduler' topic

Users of geoCML will need a topic on geoCML Desktop. This topic should have general information about the geocml-task-scheduler service, as well as information on how to write custom tasks in Python.

Quick deployment guide should have a subsection on example local deployment

with example ip & port no. that users can copy/paste into a VNC viewer or web browser

Set up geoCML documentation scaffolding

We need to provide user documentation for geoCML to enable users to quickly become productive with their deployments. I suggest that we create a separate repo in this organization to hold our documentation source code and add it to this repo as a submodule!

@capsulecorplab will be helping to develop a methodology/tool chain to use for our documentation. Once we've set up a structure for our docs, we will be adopting a docs-driven-development practice for geoCML.

'geoCML Server' topic

Users of geoCML will need a topic on geoCML Desktop. This topic should have general information about the geocml-server service, as well as information on how to customize and configure the service (including the geoCML Server Portal) to fit the needs of users' specific use cases.

Tradestudy of CMS architectures

This issue is for capturing a trade study of architectures used for content management of interest for user-facing & architecture documentation

'Introduction to geoCML' topic

Users who are new to geoCML will need an introductory topic to get them familiar with the deployment pattern. This topic should provide a general overview of the project, as provide users who are on the fence about implementing geoCML clear answers about whether or not it is an appropriate choice for their use case.

'geoCML Desktop' topic

Users of geoCML will need a topic on geoCML Desktop. This topic should have general information about the geocml-desktop service, as well as information on how to customize and configure the service to fit the needs of users' specific use cases.

'geoCML Postgres' topic

Users of geoCML will need a topic on geoCML Postgres. This topic should have general information about the geocml-postgres service, as well as information on how to customize and configure the service to fit the needs of users' specific use cases.

Add a contributor's guide

As geoCML is open-source software, we should adopt a contributor's guide instructing developers on how to contribute to this repository's source code. @capsulecorplab has already developed a template that we can adopt for our needs: https://gist.github.com/capsulecorplab/f7cf4a1e070d099f95fc8a3ae3e4ea75

typo under `How to build your documentation` in README

Run ./grawdlew generateHTML generatePDF s/b Run ./gradlew generateHTML generatePDF under How to build your documentation