README.md 2.18 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
# Center for Computational Genomics and Data Science Manual

The Manual of Operations (MOO) for the Center of Computational Genomics and Data Science provides guidance to members
of the center its mission and operations.  The manual of operations is a statically generated website using
[MkDocs](https://www.mkdocs.org) which creates a static website from MarkDown files.  The following website
<https://www.markdownguide.org/basic-syntax/> is a useful guide and cheatsheet to MarkDown syntax for formatting.

## Local Development with Docker

### Docal Pre-requesites

* [Docker](https://www.docker.com)

### Deploy Locally within Docker

If you do not want to install Python or MkDocs directly onto your system, you can use docker and docker-compose to
develop with locally. To start running the self-hosted mkdocs service to live update execute the following.
> `docker-compose up`
---

## Local Development native on computer

### Native Pre-requesites

* [MkDocs](https://www.mkdocs.org/)

### Installation

#### MacOs  

> [Homebrew](https://brew.sh/)  
`brew install mkdocs`

#### Windows

> [Choclately](https://chocolatey.org/)  
`choco install mkdocs`

## Deploy Locally

Use the following command to localy update and view hotloaded changes live.
> `mkdocs serve`

--

## Add new pages

There are two steps to add new pages to the manual of operations.
>
> 1. Create a new MarkDown file within the `docs/` directory.  MarkDown file names use Kebab Case naming scheme.
An example is `helpful-uab-information.md`.
> 2. Open the `mkdocs.yml` file within the root project directory.  Add a new line under the `nav` section within
the YAML file with the following format `- <Page Name>: <mark-down-file-name.md>`.  The MkDocs shall order the menu
the as the`nav` section in the `mkdocs.yml`.

---

## Production

The following commands can only be executed if MkDocs is directly installed on the machine. However, this will rarely
be needed when updating the MOO.

### Build Website

> `mkdocs build`

### Build and Deploy to Gitlab Pages

Reference the `.gitlab-ci.yml` file for configuration of Gitlab Pages continuous integration for deploying the mkdocs
generated website to Gitlab pages.  
> `mkdocs build -d public`