# Building Mitto Documentation

Two types of Mitto documentation can be built: single-version and
multi-version.  Single-version is the original documentation framework
that supports only a single body of documentation -- that of the
currently checked-out branch.  Multi-version is the newest framework
that supports publishing multiple versions of documentation (i.e., a
version for each Mitto release).

Generally, one wants to build multi-version documentation when
publishing documentation for a Mitto release.  Single-version
documentation is useful when in the process of developing
documentation for a release as it is much faster to produce.

.. WARNING::

   Multi-version documentation can only be built using Mitto `2.9.0`
   or later.  However, multi-version documentation created with
   Mitto `2.9.0` or later can include documentation for any Mitto
   version for which documentation exists (e.g., `2.5.1`, `2.7.5`,
   etc.).

## Public vs. Private

There is also the notion of public and private documentation.  Public
documentation is published to https://zuar.com/api/mitto and is
accessible by anyone. Private documentation is published elsewhere and
is accessible only by whitelisted IP addresses.

The `PVT` environment variable controls which documentation is being
worked with by commands.  If `PVT` is not set or if it is set to
something other than `y`, public documentation is being worked with.
If `PVT` is `y`, then private documentation is being worked with.

.. IMPORTANT::

   When working with documentation locally, only one flavor of
   documentation can be built and viewed at a time.  This is because
   the generated HTML is placed in the same directory, regardless.
   
   Thus, when publishing documentation for a release, one generally
   follows this pattern:

   * build, view, publish public documentation
   * build, view, publish private documentation

   It is not possible to build both types and then publish both
   types.

## Documentation Environment

Before documentation can be built, the environment must be setup.

.. prompt:: bash $,# auto

   $ cd $MITTO_HOME
   $ . pyenv/bin/activate
   $ cd mitto/docs
   $ make pyenv

This will install Sphinx and related packages necessary to build
documentation.

## Schemas and Release Notes

Before building the documentation, determine if the JSON schemas and
release notes need to be updated.

1. JSON schema documents.

   .. prompt:: bash $,# auto

	  $ cd docs
	  $ MITTO_DATA=/var/mitto make schemas         # public schemas
	  $ MITTO_DATA=/var/mitto make PVT=y schemas   # private schemas

   This will create JSON schema documentation locally in:
   ```
   docs/src/schemas     # public documentation
   docs/srcp/schemas    # private documentation
   ```

   Setting `MITTO_DATA`, as shown above, is usually necessary because
   it is likely to have a different, non-default, value on a developer
   machine.  The value above is the Mitto production default.  The value
   of `MITTO_DATA` is embedded in some documentation that is generated.
   
   Commit any new/changed schema documentation to version control.

2. Release notes.  For example, to create release notes for release
   `2.8.10`:

   .. prompt:: bash $,# auto

	  $ cd docs
	  $ MITTO_REL=2.8.10 make release_notes

   This will create `docs/src/release_notes/2.8.10.md`.

   Following this, manually update `docs/src/release_notes/index.md`
   to point to the newly created release notes.

   .. IMPORTANT::
      The `MITTO_REL` value must exactly match the release number used
      in Jira, as it is used to query Jira ticket information when
      building release notes.

3. If building multi-version documentation, any changes to
   documentation source resulting from the above
   **must be checked-in** to the repository
   for the changes to appear in the generated documentation.

## Single-version Documentation

With the advent of multi-version documentation, single-version
documentation is really of use only when actively developing
documentation for a release.  Working with single-version
documentation offers the following advantages:

* Documentation is built only for the *currently checked-out branch*
  This eliminates the overhead of building documentation for multiple
  releases.

* Documentation is generated from the source files present in the
  current branch -- it is not necessary to check-in changes prior to
  building documentation.  This is especially convenient when one is
  actively developing documentation.

Other differences:

* The generated single-version is placed directly under
  `docs/build/html`; it is not placed in its own subdirectory.

* Version information and selection is not present in the
  sidebar.

### Build the Documentation

   .. prompt:: bash $,# auto

	  $ cd docs
	  $ make clean
	  $ make version         # public documentation
	  $ PVT=y make version   # private documentation

### View the Local Documentation.

   .. prompt:: bash $,# auto

      $ cd docs
	  $ make serve           # public documentation
	  $ PVT=y make serve     # private documentation

   The, in your browser, navigate to `http://localhost:8000`.

### Publish the Documentation

Single-version documentation can be published in exactly the same way
as multi-version.  However, doing so will wipe-out existing
multi-version documentation.  It's unlikely that single-version
documentation should be published.

## Multi-Version Documentation

When multiple versions of documentation are built, they are 
built into `docs/build/html`. Each version is contained in its own
subdirectory.  E.g.:
```
$ tree -L 1 docs/build/html
docs/build/html
├── 2.8.6
├── 2.8.7
├── 2.8.8
├── 2.8.9
├── 2.8.10
└── master
```

A special `index.html` is built an placed in `docs/build/html`; it
automatically redirects browsers to the "current" version of the
documentation.  Links in the sidebar of each page display the version
currently being viewed and allow the user to switch documentation
versions.

Creation of multi-version documentation is controlled by
environment variables.  They can be set once or they can be provided
on the command line each time `make` is run.

The first two control the documentation that is built; they
specify the git branches and tags of interest.  Roughly, they
define the "releases" that documentation will be built for.

`MITTO_TAGS`

   A string containing a regular expression matching the tags
   for which to generate documentation.
   E.g.: `MITTO_TAGS="2.8.[89]|2.8.1[012]"`

`MITTO_BRANCHES`

   A string containing a regular expression matching the branches
   for which to generate documentation.
   E.g.: `MITTO_BRANCHES="master"`

The remaining variables fine-tune the documentation.

`MITTO_LATEST`

   A string defining the most recently released
   version of Mitto.  This is used for the `latest`
   links in the generated HTML.  It must be a valid
   tag or branch in git.
   E.g.: `MITTO_LATEST="2.8.12"`

`MITTO_REL`

   A string containing the Jira release number for which
   to create release notes.  This is only used
   when `make release_notes` is used to build release notes.
   E.g.: `MITTO_REL="2.9.0"`

`MITTO_RELEASED`

   A string containing a regular expression matching the tags or 
   branches which have been released.  This is matched against the
   full git refname returned by `git for-each-ref --format "%(refname)"`.
   E.g.: `MITTO_RELEASED='^refs/tags/2.8.(8|9|1[0-2])$'`

   This is used to classify a "release" as either "released" or in
   "development".

.. IMPORTANT::

   When building multi-version documentation the `sphinx-multiversion`
   command is used instead of `sphinx-build`.  For
   `sphinx-multiversion` to work properly, all documentation **must be
   checked-in** to the repository. Changes made locally, but not
   checked-in to the current branch, will not appear in the generated
   documentation.

### Define and Confirm What will be Built

For this example, we will update our environment with the
specifications of the documents to generate, then we'll confirm the
exact versions that will be built:

.. prompt:: bash $,# auto

   $ export MITTO_BRANCHES="(2.9.x|master)$"
   $ export MITTO_TAGS="2.8.(8|9|1[0-2])"
   $ export MITTO_LATEST="2.8.12"
   $ export MITTO_REL="2.9.0"
   $ export MITTO_RELEASED='^refs/tags/2.8.(8|9|1[0-2])$'
   $ make versions-show
   Documentation will be built for the following versions:
   [
       "2.8.10",
	   "2.8.11",
	   "2.8.12",
	   "2.8.8",
	   "2.8.9",
	   "2.9.x",
	   "master"
   ]

HINT: It may be easisest to start with the [values used](
https://www.zuar.com/api/mitto/latest/other/build_info.html
) in the most recent build of documentation and modifying them.

Let's review the values used above:
* `MITTO_BRANCHES` / `MITTO_TAGS` -- together these define the versions
  of documentation that will be created.  Nothing else controls the
  selection of documentation that is built.
* `MITTO_LATEST` -- `2.8.12` is the most recent version of Mitto that
  has been released.
* `MITTO_REL` -- development on `2.9.0` will be complete within a week
  or two.  This value is used when querying Jira for tickets to
  include in the release notes.
* Because we are nearing the release of `2.9.0`, a `2.9.x` branch has
  been created to allow ongoing new feature development to continue
  on `master`.
* `MITTO_RELEASED` -- this regex controls classifications of a
  version.  Because they do not match the regex, the `2.9.x` and
  `master` branches will both be classified as `development`.  All
  other versions will be classified as `released`.

### Build the Documentation	

.. prompt:: bash $,# auto

   $ cd docs
   $ make clean
   $ make release_notes
   # if needed, update generated release notes manually
   # $ git add <release_notes.md>
   # $ git commit -m 'NO-TICKET: <x.y.z> release notes'
   # $ git tag -m <x.y.z> <x.y.z>
   # $ git push
   $ make versions

`make versions` generates a complete set of documentation for each
release.  Documentation for each version is placed in its own
directory under `docs/build/html`.

.. IMPORTANT::
   The generated HTML (i.e., the contents of `mitto/docs/build`) is
   never checked-in to the repo; only the source documents are
   controlled.

### View the Local Documentation.

.. prompt:: bash $,# auto

   $ cd docs
   $ make serve

In your browser, navigate to `http://localhost:8000`.

### Publish the Documentation

If the local documentation looks good, publish it to `zuar.com`.

.. prompt:: bash $,# auto

   $ cd docs
   $ make publish

### Post-Release Documentation Updates

Want to update docs for a release without performing all the other
release related tasks?  Here's how.

#### Author the Changes

Assume that `2.9.4` has been released and that documentation changes
need to be made and published. `2.9.4` is a tag on the `2.9.x` branch.

On the tip of the `2.9.x` branch, create a new branch and make the
desired documentation changes and commit them.

Build the documentation and view it locally:
```
# 'make version` instead of 'make versions' saves time
make version
make serve
```

Once it looks good, commit the changes, push to github, create a PR,
merge the PR into 2.9.x, then do a `git pull`.

#### Build and Publish the Documentation

We'll adopt the convention that documentation-only updates will be
tagged by appending a `_n` to the previous release tag, where `n` is
an integer starting at `1`.  Thus, `2.9.4_1` differs from `2.9.4` only
in documentation, as does `2.9.4_2`, etc.

Create a `2.9.4_1` tag via `git tag 2.9.4_1`.

Change to the `docs` directory.

When the `2.9.4` documentation was built, the following environment
variables were set (find the variables used to build the current
documentation [here](
https://www.zuar.com/api/mitto/latest/other/build_info.html)):
```
export MITTO_LATEST='2.9.4'
export MITTO_REL='2.9.4'
export MITTO_RELEASED='^refs/tags/(2.8.([89]|1[0-2])|2.9.[0-4])$'
export MITTO_DATA='/tmp/mitto-tests'
export MITTO_TAGS='(2.8.([89]|1[0-2])|2.9.[0-4])$'
```

Update those to include our new documentation-only release:
```
export MITTO_LATEST='2.9.4_1'
export MITTO_REL='2.9.4_1'
export MITTO_RELEASED='^refs/tags/(2.8.([89]|1[0-2])|2.9.[0-4]|2.9.4_1)$'
export MITTO_DATA='/tmp/mitto-tests'
export MITTO_TAGS='(2.8.([89]|1[0-2])|2.9.[0-4]|2.9.4_1)$'
```

Make all versions of the documentation and view it:
```
make versions
make serve
```

If it looks good, publish the documentation to `zuar.com`:
```
make publish
```

Push the tag to github, if desired.

..
   comment to make the Sphinx happy