docs-source/README.adoc - pekko-platform-guide - Git at Google

 = Lightbend Akka Platform Guide 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:


 * <<Building the guide locally>>
 * <<Adding tabbed example blocks>>
 * <<Linking to section headings>>
 * <<Versioning the doc>>
 * <<Support for multiple versions>>

 == 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/).

 [source,adoc]
 ----
 = # Add page title here, the file name should be close if not identical, for SEO
 :idprefix:
 :idseparator: -
 :!example-caption:

 :page-toclevels: 3 //overide number of toc levels, default is 2. To turn off toc at page level set to -1

 :!page-supergroup-java-scala: Language //remove '!' to enable tabbed example boxes for scala and java
 :!page-supergroup-maven-sbt: Build Tool //remove '!' to enable tabbed example boxes for maven and sbt
 :!page-supergroup-maven-gradle-sbt: Build Tool  //remove '!' to enable tabbed example boxes for maven, gradle and sbt
 :!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 source 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.


 === Including a file, or file section, in the documentation

 For a file at `examples/snippets/modules/ROOT/examples/spark-scala/src/main/scala/com/example/Feature.scala`, the following statement is used to include the whole file:

 ```
  include::{cloudflow-examples-version}@docsnippets:ROOT:example$spark-scala/src/main/scala/com/example/Feature.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
 ```
 package com.example

 class Feature {
     //tag::something_interesting[]
     val abc = new Greatness()
     //end::something_interesting[]
 }
 ```

 the relevant part is added using:
 ```
  include::{cloudflow-examples-version}@docsnippets:ROOT:example$spark-scala/src/main/scala/com/example/Feature.scala[tag=something_interesting]
 ```

 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.

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

 [source,adoc]
 ----
 [.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
     ```
 --
 ----

 == Inline text examples that respect Supergroups
 Inline text will respect a supergroup preference such as Java/Scala when using the following syntax:

 === Plain Text

 [source, asciidoc]
 ----
 Plain inline text about [.group-scala]#scala# [.group-java]#java#.

 Bold styling [.group-scala]#*scala*# [.group-java]#*java*# or formatted as [.group-scala]#`scala code`# [.group-java]#`java code`#.
 ----

 == Paragraphs that respect Supergroups

 [source, asciidoc]
 ----
 [.group-scala]
 This is a Scala specific paragraph.

 [.group-java]
 This is a Java specific paragraph.
 ----

 == Admonitions that respect Supergroups

 [source, asciidoc]
 ----
 [NOTE.group-java]
 ====
 This is a *Java* specific note.
 ====
 ----

 == 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>>
 ----


 == 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 https://github.com/lightbend/cloudflow/tree/v1.3.3-docs[`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 Lightbend convention, the latest released version is called 'current' and is the default URL for the documentation landing page.
 For Akka, the landing URL is: https://doc.akka.io/docs/akka/current/

 In Akka, we call `snapshot` the version in the making.
 That is, the _latest-greatest_ changes that aren't released yet.
 The corresponding URL mapping is: https://doc.akka.io/docs/akka/snapshot/

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

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

 .Versions: Names x Branch
 |===
 |git branch | name in URL | name in docs   |
 | main      | snapshot    | 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:

 . Create a branch for the release and make it the `current` version by updating version references.
 . Update the previous release to demote it from `current` to its corresponding `x.y.z` version.
 . 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 `snapshot` in the documentation.
 When we create a new release, we need to promote `snapshot` to `current`.
 We do that by creating a new `x.y.z-docs` branch from the released version and applying the following changes in that branch:

 Update the documentation modules with their corresponding version:

 * In `docs/docs-source/docs/antora.yml`, update `version: snapshot` to `version: current`

 Change the internal version references to the new versions:

 * In `docs/docs-source/docs/modules/ROOT/partials/include.adoc`
 ** update `:cloudflow-version:` to the new  `x.y.z` version
 ** update `:cloudflow-examples-version:` to the new `x.y.z` version

 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 `master` 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: [master, 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: [master, 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.


 == 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:

 * https://docs.antora.org/antora/2.0/
 * https://asciidoctor.org/docs/
 * http://asciidoc.org/
	= Lightbend Akka Platform Guide 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:


	* <<Building the guide locally>>
	* <<Adding tabbed example blocks>>
	* <<Linking to section headings>>
	* <<Versioning the doc>>
	* <<Support for multiple versions>>

	== 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/).

	[source,adoc]
	----
	= # Add page title here, the file name should be close if not identical, for SEO
	:idprefix:
	:idseparator: -
	:!example-caption:

	:page-toclevels: 3 //overide number of toc levels, default is 2. To turn off toc at page level set to -1

	:!page-supergroup-java-scala: Language //remove '!' to enable tabbed example boxes for scala and java
	:!page-supergroup-maven-sbt: Build Tool //remove '!' to enable tabbed example boxes for maven and sbt
	:!page-supergroup-maven-gradle-sbt: Build Tool //remove '!' to enable tabbed example boxes for maven, gradle and sbt
	:!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 source 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.


	=== Including a file, or file section, in the documentation

	For a file at `examples/snippets/modules/ROOT/examples/spark-scala/src/main/scala/com/example/Feature.scala`, the following statement is used to include the whole file:

	```
	include::{cloudflow-examples-version}@docsnippets:ROOT:example$spark-scala/src/main/scala/com/example/Feature.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
	```
	package com.example

	class Feature {
	//tag::something_interesting[]
	val abc = new Greatness()
	//end::something_interesting[]
	}
	```

	the relevant part is added using:
	```
	include::{cloudflow-examples-version}@docsnippets:ROOT:example$spark-scala/src/main/scala/com/example/Feature.scala[tag=something_interesting]
	```

	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.

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

	[source,adoc]
	----
	[.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
	```
	--
	----

	== Inline text examples that respect Supergroups
	Inline text will respect a supergroup preference such as Java/Scala when using the following syntax:

	=== Plain Text

	[source, asciidoc]
	----
	Plain inline text about [.group-scala]#scala# [.group-java]#java#.

	Bold styling [.group-scala]#scala# [.group-java]#java# or formatted as [.group-scala]#`scala code`# [.group-java]#`java code`#.
	----

	== Paragraphs that respect Supergroups

	[source, asciidoc]
	----
	[.group-scala]
	This is a Scala specific paragraph.

	[.group-java]
	This is a Java specific paragraph.
	----

	== Admonitions that respect Supergroups

	[source, asciidoc]
	----
	[NOTE.group-java]
	====
	This is a Java specific note.
	====
	----

	== 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>>
	----


	== 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 https://github.com/lightbend/cloudflow/tree/v1.3.3-docs[`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 Lightbend convention, the latest released version is called 'current' and is the default URL for the documentation landing page.
	For Akka, the landing URL is: https://doc.akka.io/docs/akka/current/

	In Akka, we call `snapshot` the version in the making.
	That is, the _latest-greatest_ changes that aren't released yet.
	The corresponding URL mapping is: https://doc.akka.io/docs/akka/snapshot/

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

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

	.Versions: Names x Branch
	\|===
	\|git branch \| name in URL \| name in docs \|
	\| main \| snapshot \| 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:

	. Create a branch for the release and make it the `current` version by updating version references.
	. Update the previous release to demote it from `current` to its corresponding `x.y.z` version.
	. 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 `snapshot` in the documentation.
	When we create a new release, we need to promote `snapshot` to `current`.
	We do that by creating a new `x.y.z-docs` branch from the released version and applying the following changes in that branch:

	Update the documentation modules with their corresponding version:

	* In `docs/docs-source/docs/antora.yml`, update `version: snapshot` to `version: current`

	Change the internal version references to the new versions:

	* In `docs/docs-source/docs/modules/ROOT/partials/include.adoc`
	** update `:cloudflow-version:` to the new `x.y.z` version
	** update `:cloudflow-examples-version:` to the new `x.y.z` version

	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 `master` 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: [master, 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: [master, 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.


	== 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:

	* https://docs.antora.org/antora/2.0/
	* https://asciidoctor.org/docs/
	* http://asciidoc.org/