Guidelines for Documentation

Contributing to the documentation is as easy as writing in text files. The VIVA+ documentation is written in Markdown (See this 60-second guide to Markdown). The documentation is build with MkDocs.

Golden path: Writing Documentation

1. Find the markdown file corresponding to documentation page you would like edit in /docs
2. Edit the markdown in any text editor
3. If you would like to add reference
   • Add the reference to the BibTeX file viva-refs.bib in the root directory
   • Paste the key (e.g., @AuthorYear) where you want to cite the reference
4. If you would like render the HTML pages, use command mkdocs serve within the vivaplus directory to start a local server

If the changes you would like make are small (like fixing typos, adding details to existing section), then all you need to do is add the content in the mardown files and send a merge request. However, if you are adding a new section or would like to see how MkDocs renders the documentation as HTML pages, then you will need to install MkDocs locally.

Quick Introduction to Basic Markdown

**Headings and paragraphs**
```
# h1

## h2

### h3

#### h4
```

paragraphs are separated by blank lines

**Lists**
```
* unordered list item 1
* unordered list item 2

1. ordered list item 1
2. ordered list item 2
    1. nested list item 1
```
**Text Formatting**
```
*italicized*

**bolded**

***bold and italic***
```

**Linking**
```
[link text](link url)

![image text](image link)

<quick url or email link>
```

Install MkDocs

MkDocs is a python library and easiest way to get started is using the Anaconda installation. When you have Python installed, install MkDocs using pip.

pip install mkdocs

Also, install the mkdocs extensions used by VIVA+ documentation:

pip install mkdocs-material
pip install mkdocs-bibtex
pip install pymdown-extensions

If you don't have pip installed

python get-pip.py

Or if you need to upgrade

pip install --upgrade pip

MkDocs Extensions in VIVA+ documentation

Extensions are used to enhance markdown features for MkDocs. These are listed in the mkdocs.yml.

The extensions currently used in the documentation are:

• PyMdown
• mkdocs-bibtex for bibliography
• MkDocs Material Theme for layout

Starting a local MkDocs server

You can preview your documentation as you work on it by starting the built-in dev-server. To start the server, go to the same directory as mkdocs.yml and run mkdocs serve

Open http://127.0.0.1:8000/ in the browser to see the live documentation home page

Guidelines for formatting

• To format equations or math expressions: enclose them within $ character (for example, $F = m.a$ will be rendered as $F = m.a$)
• To use subscripts or subscripts: use _ of ^ within $ characters (for example, mm$^2$ will be rendered as mm$^2$)

Adding References

mkdocs-bibtex extension is used to add citations from a Bibtex file.

The Bibtex file for VIVA+ documentation can be found in the root directory: viva-refs.bib

Please do not rewrite the whole Bibtex file as it is version controlled. You can either manually append Bibtex entries or use a Bibtex manager.

Recommended Bibtex manager : Jabref

Tips for writing technical documentation

This section of the documentation is under development

This section is being updated

Clause Order ¹

If possible, mention the circumstance before you provide the instruction; that way, the reader can skip the instruction if the circumstance doesn't apply.

Example:

• (Not recommended) See [link to other document] for more information.
• (Recommended) For more information, see [link to other document].

Documentation Hacks

Tables

• Add line break within table: <br/>

• Find emoji tags here

Figures

• Change image size ![repo](/img/repo_vivaplus.png){: style="height:500px;width:500px"} Enable attr_list in markdown_extension setting of mkdocs.yml for this to work

• Image alignment

  ![my image](/img/myImage.jpg#left)
  ![my image](/img/myImage.jpg#right) 
  ![my image](/img/myImage.jpg#center)
  

  and add this to extra.css

  img[src*='#left'] { 
      float: left;
  }
  img[src*='#right'] { 
      float: right;
  }
  img[src*='#center'] { 
      display: block; 
      margin: auto; 
  }
  

  Source: msudol

Something else to try from github issues

Comment out temporary sections in Markdown

<!---
your comment goes here
and here
-->

Source: Stackoverflow

---

1. Google Developers Course on Technical Writing ↩