[[antora-publish-procedure]]
= Publishing the Docs

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:page-partial:


WARNING: TODO: v2 - not yet updated.
There is relevant material in xref:post-release-successful.adoc[Post Release (Successful)], specifically:
 xref:post-release-successful.adoc#generate-website[Generate website] and
 xref:post-release-successful.adoc#publish-website[Publish website].



Apache Isis' documentation (meaning the website and the users' guide, the reference guide and this contributors' guide) is written using link:https://asciidoctor.org/[Asciidoctor] syntax, and organized to be published as an link:https://antora.org[Antora] website.

The website and guides are created by running build tools (documented below) which create the HTML version of the site and guides.
You can therefore easily check the documentation before raising a pull request (as a contributor) or publishing the site (if a committer).

For details of authoring/updating the documents and website, see the xref:conguide:documentation:about.adoc[Contributors' Guide].

Publishing is performed by copying the generated HTML to a different git repository (link:https://github.com/apache/isis-site.git[isis-site]).
This is synced by ASF infrastructure over to link:http://isis.apache.org[isis.apache.org].
This can only be done by Apache Isis committers, and is discussed below.

== One-time setup

The generated site is published by copying into the `content/` directory of the https://github.com/apache/isis-site.git[isis-site] git repo.
You therefore need to check this out this repo.

The procedure assumes that two git repos (for https://github.com/apache/isis[isis] itself on github, and for isis-site) are checked out into the same parent directory, eg:

[source]
----
/GITHUB/
  apache/
    isis/                       # <1>
      adocs
        documentation/
          README.adoc
          ...
    isis-site/                  # <2>
      content/                  # <3>
----
<1> checkout of isis.git
<2> checkout of isis-site.git
<3> the published website

One oddity; ASF's script to upload the documentation to the web server checks out from the 'asf-site' branch, NOT from the 'master' branch.
Therefore, in the `isis.git` repo site:

[source,bash]
----
git checkout asf-site
----

== Preview


To preview changes (ignoring PDFs), run:

[source,bash]
----
sh preview-html.sh
----

This will update the documentation and start a (Python) webserver so that the documents can be viewed.

If you want to also view the PDFs, use:

[source,bash]
----
sh preview-pdf.sh
----

There's generally little point in doing this, however.

== Publishing (full build)

WARNING: TODO: v2 - not yet updated.
Need to figure out how to merge the v1 docs (as an archive) with Antora.
Also, need to use Antora versioning rather than just 'master'

The `content` directory for the published website contains not only the "current version" of the docs, but also has an archive of older versions of the document from earlier releases:

[source]
----
/GITHUB/
  apache/
    isis-site/
      content/                  # <1>
        index.html              # <2>
        *                       # <3>
        versions/
          current/              # <4>
          SNAPSHOT/             # <5>
          ...                   # <6>
          latest/               # <7>
----
<1> the published website
<2> home page.
This has a drop-down to access older versions of the documentation, but most links are through to the "current version"
<3> documentation for the current release version
<4> also holds documentation for the current release version
<5> documentation for the next snapshot version, ie work-in-progress
<6> other versions, by version number (eg `1.16.2`, `1.16.1`, etc)
<7> not checked into git, this is a working directory that contains the results of the latest publication build.
This is an implementation detail actually, so this directory need not be considered further.

The earlier versions of the documentation are (obviously) not recreated when the documentation is published, only the current version is updated.

To publish the current version of the documents, switch to the  `adocs/documentation` directory of the main `isis-git.repo`.
Then run:

[source,bash]
----
sh publish.sh "ISIS-nnnn: a custom commit message"
----

This does the following:

* deletes everything under `content` (except `content/versions`)
* generates documentation and copies to `content/versions/SNAPSHOT`
+
Including fixing up line endings, standardizing on unix-style LFs.
* copies over current home page (`index.html`)
* reinstates `content/*` with the contents of `content/versions/current`

In other words, the effect of running `publish.sh` is in essence to overwrite `content/versions/SNAPSHOT` and to overwrite `index.html`, but leave everything else as it is.

[NOTE]
====
The version on the header of each generated document is hard-coded in the `adocs/template/document.html.erb` file.

This should therefore be updated whenever working on a new release.
====

=== New release

WARNING: TODO: v2 - not yet updated.
Need to figure out how to merge the v1 docs (as an archive) with Antora.
Also, need to use Antora versioning rather than just 'master'

When a new release is published, we therefore need to do a little extra work:

* run `publish.sh` a first time
+
This will update `content/versions/SNAPSHOT`
* delete `content/versions/current`
* rename `content/versions/SNAPSHOT` to `content/versions/current`
* run `publish.sh` a second time.
+
This has the effect of "promoting" `content/versions/current` to `content/*`

* (optionally) also copy `content/versions/current` to `content/versions/N.N.N`
+
where `N.N.N` is the release number

Ensure in doing this that the dropdown for the home page correctly references the versions.

When ready, then stage, commit and push the changes (in the `isis-site.git` directory, of course):

[source,bash]
----
git commit -am "ISIS-nnnn: updating docs"
git push
----



