# Unicado Pages
This repository contains the static website of UNICADO which is hosted by GitLab *pages*.
We are using `mkdocs` as the static site generator to generate the website from *markdown* files.

## Preview
> It is assumed you have a working :snake: **Python** installation in the following!

You can preview the website after cloning it. First you need to install `mkdocs` and the used theme by:
```sh
pip install mkdocs mkdocs-material mkdocs-glightbox
```

Then you can change the directory to the repository and run
```sh
mkdocs serve
```

This will start a local webserver which you can access with your webbrowser and preview the website.

### with pipenv
You can also start the server inside a virtual environment using `pipenv`:
```sh 
pipenv run mkdocs serve
```

## Further Documentation
For features of the site generator and its theme please refer to their excellent documentation:

- [⤷ MkDocs](https://www.mkdocs.org/user-guide/)
- [⤷ MkDocs Material](https://squidfunk.github.io/mkdocs-material/)

## Page Template
The pages are written in plain *markdown*.
The site generator has the option the extract some meta data from the content.
A template might look like this:
```
---
title: Displayed Title of Page
summary: Summary of the page content.
authors:
    - Author 1
    - Author 2
date: yyyy-mm-dd
---
# MyPage

<Content goes here>
```

# Tools
The documentation page uses some custom tools to enable a seamless continuous documentation:

## document_aircraft_xml.py
> Script

This script is used to document the aircraft exchange file.
It parses the XML file and creates the documentation for each node using its description.

The usage is explained in the output when calling the script with the `--help` option:
```sh
usage: document_aircraft_xml.py [-h] [--title title] [--level level] filename

Converts an aircraft XML file to a markdown file. The output is streamed to stdout and can be piped to a file.

positional arguments:
  filename       The XML file to convert.

options:
  -h, --help     show this help message and exit
  --title title  The title of the output page. This also sets the root node which is used to create the document.
  --level level  The maximum level nodes to be used as headers.
```