Cloudflow Documentation

This folder contains the sources for the Cloudflow web site and the Cloudflow documentation

This folder is structured as follows:

• The root directory contains the makefile for the documentation generation process.
• The source files for the home page and other root pages in the website are located under homepage-source/.
• The structured documentation is located under docs-source/, with content that is shareable located in shared-content-source. See the readme.adoc file in the shared-content-source folder for more information.

Additionally, the style used to generate the published website is available at: https://github.com/lightbend/antora-ui-lightbend-cloud-theme

Contributions to the documentation are welcome and encouraged. If you are unfamiliar with the project or with asciidoc, please read the contribution guidelines below.

Contributing to the Cloudflow Documentation

Detailed information about working with the documentation is provided in the docs-source folder. A good starting point is to build the documentation in "author-mode" with the make html-author-mode command.

Building the Documentation

The Cloudflow documentation is built using Antora, from asciidoc sources. The building process is managed by make using the makefile script.

To build the documentation, use make with the following commands:

make all (default):: Generates the complete documentation bundle, including the Cloudflow docs, the website pages, and the java and scala docs. The result is available at docs-source/build/site/

make html:: Generates from the upstream git repository the html documentation (result available at docs/target/staging/docs/<version>) and homepage (result available at docs/target/staging).

make html-author-mode:: Generates from the local folders the documentation (result available at docs/target/staging/docs) and the homepage (result available at docs/target/staging), in 'author' mode, to display review comments and TODOs.

• make check-links

  Checks that the external links point to a reachable URL.

• make list-todos

  List all the TODOs, review comments, unresolve references, etc. from the documentation.

• make local-preview

  Builds the documentation and starts a local HTTP server, useful for writing docs and verifying the documentation. Point your browser to http://127.0.0.1:8000/docs/dev/ and check the docs.

Updating a current version of the documentation

See docs-source/README.adoc

Adding a new version of the documentation

See docs-source/README.adoc

TODO: copy the asciidoc help from the old user-guide README.