# Documenting MagAO-X¶

## Where the documentation lives¶

This source code for this documentation lives in the magao-x/handbook repository. Parts of the documentation pertaining to the core C++ code are generated from the code in magao-x/MagAOX, which is documented in Doxygen. (TODO: explain how to make cross-references.)

The built copy of this documentation is hosted at https://magao-x.github.io/handbook/ via GitHub Pages free hosting. When changes are pushed to the master branch of magao-x/handbook, a CircleCI job builds and updates the gh-pages branch of the repository, with changes reflected on the GitHub Pages site 1-15 minutes later.

## How to make changes¶

The first time you make an edit:

1. Click “Fork” on magao-x/handbook to make your own copy of the documentation to edit

3. Change into the directory where you just cloned the documentation and run pip install -r requirements.txt to install software so you can preview your changes.

You now have a copy of the sources for the handbook. If you’re just editing an existing document, skip ahead. Otherwise, here are the special instructions for creating a brand new document:

1. Create a .md (or .rst, see below) file with the name you want

2. Find the file with the appropriate .. toctree:: directive (probably index.rst) and edit it to add the base name of your file (e.g. funny-business.md would be funny-business in the toctree)

Finally, to preview and publish your edits:

1. Edit the document you want to change

2. Run make html (in the directory you cloned into)

3. Open _build/html/index.html to see the updated site, and verify your changes look good

4. git add ./path/to/file/you/changed.md and git commit -m "Description of your changes"

5. git push origin master

6. Return to magao-x/handbook and click the button to create a new pull request

If everything looks good, your changes will be merged by someone and the public copy of the docs will update automatically!

### Markup¶

Documents can be written in Markdown (CommonMark variant), in which case the filename must end with .md, or reStructuredText, in which case the filename must end with .rst. If you want to see how a particular bit of formatting was achieved, you can click the “Page source” link at the bottom of the page.

The following examples are written in Markdown, since that is the language most new contributors are likely to be familiar with. Accomplishing trickier formatting may require dipping one’s toes into reStructuredText or mixing both languages.

To link to a section within the same document: [my link text](#my-section-title) makes a link to a section headed “My Section Title” with “my link text” as the clickable text. All spaces are converted to dashes, and capitalized letters are converted to lowercase.

### Code samples¶

#### Inline code¶

To include some code inline, enclose it in backticks (left of the 1 key on most US keyboards).

Example markup:

Before starting, execute sudo do-things in your terminal


Output:

Before starting, execute sudo do-things in your terminal

#### Blocks of code¶

Blocks of code are “fenced” by three backticks on their own line before and after the code block. (If you need to include such a sequence in your block of code, you can use three tildes instead.)

Example markup:


for i in range(8):
print("Step", i)



Output:

for i in range(8):
print("Step", i)


#### Syntax highlighting¶

By default, the documentation system applies syntax highlighting for Python code to code blocks. If your code is in another language, you include its name on the line after the first set of backticks.

Example markup:

bash
#!/bin/bash
set -exuo pipefail
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" cd "$DIR"



Output:

#!/bin/bash
set -exuo pipefail
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" cd "$DIR"


### Math¶

Equations can be inserted as a special variety of code block.

Example markup:

math
\mu = m - M = 5 \log_{10}\left(\frac{d}{10\,\mathrm{pc}}\right)



Output:

$\mu = m - M = 5 \log_{10}\left(\frac{d}{10\,\mathrm{pc}}\right)$

### External files¶

If you want to include a downloadable file (e.g. filter transmission curve table, PDF document, etc.) you will have to dip your toes into the “embedded reST” feature of reCommonMark.

Example markup:

eval_rst
:download:Click here to download the star logo <mini-star.png>



Output:

Click here to download the star logo

Alternatively, you can simply write the whole document in reStructuredText as in the Preliminary design review page.

### Images¶

By default, images are included inline and left aligned. Image inclusion takes the form ![](path) where path is the path relative to the current file you’re editing.

Example markup:

![](mini-star.png)


Output:

Note: reCommonMark does not correctly handle “alternative text”, normally placed between the square brackets, meaning the alt= attribute is not populated and the handbook is not as accessible to the visually impaired as it could be.

## Implementation details¶

This documentation is assembled with a Python-based tool called Sphinx. Sphinx uses the files to make the docs.