How to contribute to the Documentation¶

Contributing to the documentation is an easiest way to become a contributor to any open source project. The VIVA+ documentation is written in Markdown.(1)

(See this 60-second guide to Markdown)

Summary: Contributing to Documentation

Start an issue on the VIVA+ repo to indicate what you will be writing in the documentation.
Create a merge request and branch from this issue, so that you have your branch to work on
Find the markdown file corresponding to documentation page you would like edit in /docs folder. The files follow the same arrangement as the URL of the pages.
Edit the markdown in any text editor
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
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 markdown file. However, if you are adding a new page 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¶

This documentation is build with MkDocs. MkDocs is a python library. If you have already have Python installed, MkDocs can be installed using pip.

pip install mkdocs

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

pip install mkdocs-material
pip install mkdocs-bibtex
pip install mkdocs-git-revision-date-plugin
pip install mkdocs-video==1.1.0
pip install mkdocs-rss-plugin

Starting a local MkDocs server¶

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

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 superscripts: use _ or ^ within $ characters (for example, mm$^2$ will be rendered as mm $^2$ )

Adding References¶

All the references in this documentation are collected in a BibTex file in the /vivaplus/docs/ subdirectory: viva-refs.bib.¹ When you have added your reference to this BibTeX file viva-refs.bib, use the the Bib key (e.g., @AuthorYear) to cite the reference in the documentation.

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. It is recommended to use Jabref to manage the BibTeX file

Tips for writing technical documentation¶

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

mkdocs-bibtex extension is used to add citations from a BibTex file. ↩
Google Developers Course on Technical Writing ↩