# ASEA Documentation using Mkdocs

This is the source code for the ASEA documentation
site that is hosted on github pages.

## Development

This site uses mkdocs under the hood to generate
the site static html content.

In addition, [mike](https://github.com/jimporter/mike)
is used to version the documentation.

### Getting Started

Make sure you have configured a virtual environment.

```bash
python -m venv venv
source venv/bin/active
pip install --upgrade pip && pip install -r requirements.txt
```

### Mike

Mike is used to version the website. The CI step `deploy`
in [docs.yml](../../.github/workflows/docs.yml#L33) is
responsible for deploying the versioned content using
a github actions bot onto the `gh-pages` branch.

In order for the CI to deploy an updated version of the
documentation, a git tag and corresponding release must be
created.

The workflow is as follows:

```bash
git checkout -b feat/your-feature
... open vscode and make changes ...
git add .
git commit -m "feat: added foo"
git push -u origin feat/your-feature
```

Updating these references to your new release tags ensures
that embedded links in the documentation are pointing to
the correct versioned resource.

Open a pull request, and then merge.
Once the changes are merged onto the main branch,
a github workflow is triggered which will lint and
test that the site builds correctly. Once you have verified
that the actions have all run successfully, create a git tag
and push it.  Do not forget to update any tag references in links throughout the documentation.
These can be updated using the provided [versioner script](versioner.sh)

```bash
./versioner.sh -o vX.X.X -n vY.Y.Y
git tag vY.Y.Y
git push -u origin vY.Y.Y
```

Next, generate a release from the git UI. This will trigger
a deployment of the docs site (see [docs.yml](../../.github/workflows/docs.yml#L33)).

#### Important Note Regarding the gh-pages Branch

Note the structure of the `gh-pages` branch. This structure
is generated by `mike` and is updated from each `deploy` step
in the github action. If you are looking to implement versioning,
you should restructure your `gh-pages` branch locally, push
the changes, and then `mike` will take it from there.

To restructure your repository locally:

```bash
git checkout gh-pages
rm -r *
git push -u origin gh-pages
```

Now the CI will be able to run succesfully and start versioning
your docs repo.