Skip to content
This repository was archived by the owner on Nov 22, 2024. It is now read-only.

docs-source

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs-source

README.adoc

Lightbend Cloudflow Docs README

The source files for this guide use asciidoc syntax and the project is configured to build with Antora. To review and suggest changes, we recommend building the HTML files locally. This allows you to view the guide structure as a whole and to read pages the way someone using the documentation would.

This readme covers the following topics:

Support for multiple versions

The documentation structure and supporting scripts is set up to allow the easy evolution of versioned documentation alongside the main project. Each version is maintained in a separate branch that stems from the release that generated the new version. For example, for v1.3.3 of the documentation, there’s a v1.3.3-docs branch that contains the version of the documents and links to the examples that corresponds to the Cloudflow 1.3.3 release.

Version numbers

As per internal Lightbend convention, the latest released version is called 'current' and is the default URL for the documentation landing page. For Cloudflow, the landing URL is: https://cloudflow.io/docs/current/index.html

In Cloudflow, we call dev the version in the making. That is, the latest-greatest changes that aren’t released yet. The corresponding URL mapping is: https://cloudflow.io/docs/dev/index.html

Any other version, is addressed by its explicit version number. For example: https://cloudflow.io/docs/1.3.3/index.html

In general, the versions produced by our documentation process follow the current mapping to names and git branches:

Table 1. Versions: Names x Branch

git branch

name in URL

name in docs

main

dev

x.y.z-SNAPSHOT

x.y.z-docs for the most recent x.y.z release

current

x.y.z

x.y.z-docs for older releases

x.y.z

x.y.z

Adding a new version

Adding a version of the documentation for a new release requires three steps:

  1. Create a branch for the release and make it the current version by updating version references.

  2. Update the previous release to demote it from current to its corresponding x.y.z version.

  3. Update the Antora configuration with the new branches.

Creating a new current version

As we saw in the previous section, the latest development is called dev in the documentation. When we create a new release, we need to promote dev to current. We do that by creating a new x.y.z-docs branch from the released version and, after a new release has pushed it’s tag run:

make set-antora-versions

Note that internally, we use the actual version number to name our modules, while only the external-facing docs-source is called current to comply with the Lightbend conventions.

Demoting the previous release

Now that we have a new current version, we need to demote the previous release to use its x.y.z release (instead of current)

In the branch that corresponds to the previous release, let’s call it x.w.v-docs, make the following update:

  • In docs/docs-source/docs/antora.yml, update version: current to version: x.w.v

Commit these changes to the x.w.v-docs branch.

Note
 All internal versions should already match this version.

Adding the new branch to the Antora build list

At this point, we should have a new x.y.z-docs branch that corresponds to current and an updated x.w.v branch with the renamed current version to its explicit x.w.v version. At this point, in the main branch, we must add the new branch to the Antora site.yaml which informs the branches used when building and publishing the documentation.

In docs/docs-source/site.yml, find the line that list the branches included in the build. It looks like this:

 branches: [main, vx.w.v-docs]  # versioned content - add branches here

Then follow the advice in the comment and add the new vx.y.z-docs branch to the list :-)

The updated version would look like:

 branches: [main, vx.y.z-docs, vx.w.v-docs]  # versioned content - add branches here

After merging this update to main, the CI script will pick up the new branch, generate the corresponding docs, and publish it to the external site.

Building the guide locally

Building the Antora site is managed by the Makefile at the root of the project. List of all available target is available in the top level README.

A few selected commands:

  • make html - build the antora site.

  • make html-author-mode - build the antora site in author mode, with the todo and reviewer attributes rendered in the output.

The result of the build is available in the target/staging/ directory.

Creating new pages

To create a new page, start your file with a title and select from the following attributes. You only need to use the supergroup attribute for the type of examples a page will include. The tabbed example boxes are specific to the Lightbend skin that we build against. (https://github.com/lightbend/antora-ui-lightbend-theme/).

= # Add page title here, the file name should be close if not identical, for SEO
:idprefix:
:idseparator: -
:!example-caption:
:toc: // enables page-level toc, to disable for pages with no sub-heads, add a !, :!toc:
:toc-title: ON THIS PAGE
:toclevels: 2
:!page-supergroup-scala-java: Language //remove '!' to enable tabbed example boxes for scala and java
:!page-supergroup-sbt-maven: Build Tool //remove '!' to enable tabbed example boxes for sbt and maven
:!page-supergroup-sbt-maven-gradle: Build Tool  //remove '!' to enable tabbed example boxes for sbt, maven, and gradle
:!page-supergroup-minishift-minikube: Platform  //remove '!' to enable tabbed example boxes for Minishift and Minikube
:!page-supergroup-kubernetes-openshift: Platform //remove '!' to enable tabbed example boxes for Kubernetes and OpenShift
:!page-supergroup-mac-ubuntu: OS //remove '!' to enable tabbed example boxes for Mac and Ubuntu

When you add a new page, you must also add it to the nav.adoc file in the docs/modules/ROOT directory.

Adding code snippets

Any code snippets, being Scala, Java or Blueprint must not be hard-coded inside the documentation source.

Hard-coded code will get out-of-sync with the main Cloudflow repository, and will give bad information to the users at some point.

The rule is that code snippets must be in a project, which is checked against the current version of Cloudflow.

In pratice, the code snippets are to be in a project under the examples/snippets/modules/ROOT/examples folder in the cloudflow repository. This location is configured so files, or sections of file, can be included from it into the documentation.

As a general rule, limit the number of projects at this location: one project per runtime/language for standalone snippets, one project per runtime/language for the tutorial sections.

Including a file, or file section, in the documentation

For a file at examples/snippets/modules/ROOT/examples/akkastreams-scala/src/main/scala/cloudflow/akkastreamsdoc/RecordSumFlow.scala, the following statement is used to include the whole file:

 include::{cloudflow-examples-version}@docsnippets:ROOT:example$akkastreams-scala/src/main/scala/cloudflow/akkastreamsdoc/RecordSumFlow.scala[]

In most case, including the complete file is not optimal. It is better to include only section of it. To do this, use tags.

With the following file

object RecordSumFlow extends AkkaStreamlet {

  //tag::definition[]
  val recordsInWindowParameter = IntegerConfigParameter(
    "records-in-window",
    "This value describes how many records of data should be processed together, default 64 records",
    Some(64)
  )
  //end::definition[]

the relevant part is added using:

 include::{cloudflow-examples-version}@docsnippets:ROOT:example$akkastreams-scala/src/main/scala/cloudflow/akkastreamsdoc/RecordSumFlow.scala[tag=definition]

Antora has a good support for the tags:

  • the same tag key can be used to extract multiple section of code in a file

  • multiple tag keys can be defined, to extract different section.

  • when a tagged section is requested, all the other tag comments are automatically removed from the imported code.

Adding tabbed example blocks

To add tabbed example blocks to a page, use the following syntax:

[.tabset]
Mac::
. Download and install VirtualBox: https://www.virtualbox.org/wiki/Downloads[https://www.virtualbox.org/wiki/Downloads].
Ubuntu::
+
--
Follow these steps to install Virtualbox on Ubuntu 16.04+:

. If you do not have `curl`, install it:

    ```bash
    sudo apt-get install curl
    ```

. Use the following command in a shell to download and install VirtualBox:

    ```bash
    sudo apt-get install virtualbox virtualbox-ext-pack
    ```
--
Note
 For more examples of tabbed example blocks, or to request an addition to the tabs, see https://github.com/lightbend/antora-ui-lightbend-theme/

Linking to section headings

Antora creates anchors for each section heading by default: they start with a leading _, and they include the full title of the section in lower case separated by underscores. So, unless you want to provide a shorter way to x-ref, no need to define the section anchors.

For example, using the default anchors, the following creates a cross-ref to the mypage page, Reference this heading section:

xref:mypage.adoc#_reference_this_heading[Reference this heading]

Interestingly, on the same page, you can use the following notation including spaces and mixed case and antora converts the link to the correct format.

<<Title of section>>

For reference

Antora is built on top of Asciidoctor. One of the main differences between Asciidoctor and Antora is that Antora requires a specific directory structure. If you are new to Antora and asciidoc, the following references might be helpful: