We can use Gitlab to host our documentation by exploiting the fact that Gitlab
We utilize Gitlab's built in wiki feature to host markdown files natively in browser. Previous teams stored documentation in README.md files in the repository directory. While this approach is good for having documentation near the source code, It make searching the documentation more difficult. Moving the documentation to the Gitlab wiki, allows for the separation of source code from documentation, improving searchability.
automatically renders Markdown (.md) files as HTML in the browser, making it
easy to read and show images.
Also note the wiki has been included in the main repo as a submodule, under the wiki folder. In order to clone it run `git submodule update --init`.
# Organization
# Organization
We will be using the top-level `README.md` as our main page for documentation.
We will be using the top-level `README.md` as our main page for a brief introduction and as a link to the Gitlab wiki.
You might notice that this page is automatically rendered on our [main Gitlab
You might notice that this page is automatically rendered on our [main Gitlab
project page](/../).
project page](/../tree/master).
Ideally, all documentation should be reachable from links on this main page.
Important documentation, such as getting started guides, and a general documentation outline should be linked directly on this page.
For documentation that is whole-project encompassing, those links should go
on the main page itself. For documentation that is sub-topic specific (quad,
ground station, controls), add an appropriate link on the sub topic's README.md
page. See the Quad section for an example.
Ideally, all Markdown (.md) files should go inside some `doc` or `documentation`
For documentation that is whole-project encompassing, They are place in the root directory of the wiki. For documentation that is sub-topic specific (firmware, ground station, test stand) they are to be place in their respective wiki directories.
folder (with exception to the READMEs).
# Editing
# Editing
If you are familiar with Markdown and Git, you can just edit the documentation
If you are familiar with Markdown and Git, you can just edit the documentation
from within your normal Git workflow.
from within your normal Git workflow.
However, Gitlab also makes is relatively easy to edit Markdown pages for
However, Gitlab also makes is relatively easy to edit Markdown pages for
documentation right in the browser. To edit a Markdown page, select "Edit" at
documentation right in the browser. To edit a Markdown page, select the pencil icon at the top right. This will bring up an editor that you can use to make changes. To preview the final project, use the "Preview" tab at the top left. To achieve desired formatting, you will need to use the Markdown syntax - see the [Gitlab Markdown reference](https://docs.gitlab.com/ee/user/markdown.html).
the top right. This will bring up an editor that you can use to make changes.
To preview the final project, use the "Preview" tab at the top left. To achieve
To create a new file within the wiki, go to the "wiki" tab and then select the "New page" button in the upper right. From here, you can create a new Markdown file. Note, to place a page under a directory in the wiki, specify the path in the page title: `path/to/page/page title`
desired formatting, you will need to use the Markdown syntax - see the [Gitlab
**Linking to other wiki pages** is easy. Simply surround the link text with square brackets `[This is my link text]` then directly follow it with the absolute or **relative** link in parentheses, `[absolute link test](https://www.google.com/)`
To create a new file within Gitlab, go to the "Repository" tab and then "Files"
[absolute link test](https://www.google.com/)
tab. As you navigate through our files, you will see a "+" (plus sign) button.
`[relative link test](/Home)`
From here, you can create a new Markdown file, upload a new file, or create a
[relative link test](/Home)
folder (say if you need to create some `doc` folder).
**Linking from the wiki to files in the main repository** is a little more tricky, It technically isn't supported by Gitlab anymore ([see discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/15602#note_585740398)), however there is a work around.
When linking to a file in the repository, the relative link will look like this, `/../blob/master/<path to file in repo>` . However this method fails if there is a period anywhere within the path (likely caused by how Gitlab parses relative links in a wiki). So to work around this, replace any period with the ASCII equivalent `%2E`. The browser will convert this back to a period and go to the correct address.
