# Meta Documentation

Here you will find documentation about the documentation

# VuePress

This documentation uses VuePress to render basic mark down files as a static webpage.

In the past the team has used Latex to write documentation. While Latex is good for writing final documents, VuePress gives a more streamlined workflow that is easier for new members to jump into reading documentation and especially editing documentation.

# Contributing to the Documentation

The easiest way is to click the "Edit this page" button at the bottom of the page you'd like to contribute to. The VuePress site is pre-configured with the OpenUAS git repository to automatically rebuild and deploy when a change to the Documentation folder is pushed to the main branch. The build status can be viewed on the Github actions page (opens new window)

You can also make modifications to the docs folder from any text editor, then push to the main branch and your changes will be built and published. To test your changes before publishing them, you'll need to setup a development environment:

# VuePress Personal Development Environment

To build the docs you will need a few things:

Clone the documentation repo locally

git clone git@github.com:Open-UAS/Open-UAS.github.io.git

install node.js and npm
- Downloading and installing Node.js and npm (opens new window)
install Vuepress dependencies
```
cd Open-UAS.github.io/
npm install
```
1
2
Build and run the docs from your local machine. Run npm run dev from the root folder to start the server.
Open a web browser to http://localhost:8080/ to see your local changes.

Once everything looks good on your machine, you should be able to push your changes to main to publish.

# Adding a New Page

To create a new page, simply create a markdown file (.md) in the appropriate folder. To add your new page to the sidebar, the SUMMARY.md file must be modified. This file exists in the base folder for each section (ie, Design, Electrical, Software) and is used by a script at compile time to generate the side bar information. Any relative or external link can be added to the side bar, but it is good practice to follow the actual folder structure where the files are stored.

Below is an example of the SUMMARY.md file with the following folder structure.

Docs
|-- Intro
|   |-- SUMMARY.md
|   |-- README.md
|   |-- ProjectCharter.md
|   |-- Example_Folder
|   |   |-- README.md
|   |   |-- example_file.md
|   |   |-- Example_Sub_Folder
|   |   |   |-- README.md
|   |   |   |-- example_sub_file.md

# Summary

* [New Member Orientation](README.md)
* [Project Charter](ProjectCharter.md)
* [Example Folder](Example_Folder/README.md)
     * [Example file](Example_Folder/example_file.md)
     * [Example Sub Folder](Example_Folder/Example_Sub_Folder/README.md)
          * [Example Sub File](Example_Folder/Example_Sub_Folder/example_sub_file.md)

1
2
3
4
5
6
7
8

The headings of each page are automatically detected and displayed by vuepress and cannot be easily changed.

To see more details on the side bar see .vuepress/config.js (opens new window) and .vuepress/sidebar_provider.js (opens new window)

# LaTeX Conversion

Pandoc (opens new window) can be used to convert from a LaTeX file into a mark down file.
- pandoc -s example.tex -o example.md
- This was first tested on the new member orientation page
Vuepress mathjax plugin (opens new window) is used for inline LaTeX.

# Vuepress Configuration

There are many configuration settings that Vuepress supports. Most of them are found in the docs/.vuepress/config.js file or at the top of the markdown file as front matter. More information on configuration settings can be found at the official Vuepress documentation (opens new window) Front matter details (opens new window)

# Vuepress 2.0

As of this writing (April 2022) Vuepress 1.0 is nearing its end of support and Vuepress 2.0 (opens new window) will soon be released. Currently these docs are written in Vuepress 1.0 but will need to be converted to Vuepress 2.0 eventually. A guide on the required steps should be available in the official Vuepress 2.0 docs (opens new window)