1. Purpose of this documentation

This documentation aims to cover the information required to run scientific and data-intensive computing tasks at Mila and the available resources for its members.

It also aims to be an outlet for sharing know-how, tips and tricks and examples from the IDT team to the Mila researcher community.

1.1. Intended audience

This documentation is mainly intended for Mila researchers having access to the Mila cluster. This access is determined by your researcher status. See Roles and authorisations for more information. The core of the information with this purpose can be found in the following section : Mila research computing infrastructure information and policies.

However, we also aim to provide more general information which can be useful outside the scope of using the Mila cluster. For instance, more general theory on computational considerations and such. In this perspective, we hope the documentation can be of use for all of Mila members.

1.2. Contributing

See the following file for contribution guidelines :

# Contributing to the Mila Docs

Thank you for your interest into making a better documentation for all at Mila. Here are some gidelines to help bring your contribbutions to life.

## What could be included

* Mila cluster usage
* Compute Canada cluster usage
* Job management tips / tricks
* Research good practices
* Software development good practices
* Useful tools

## Issues / Pull Requests

### Issues

Issues can be used to report any error in the documentation, missing or unclear sections, broken tools or other suggestions to improve the overall documentation.

### Pull Requests

PRs are welcome! Reference the related issues like this:

```
Resolves: #123
See also: #456, #789
```

You can attempt to build the docs yourself to see if the formating is right:

```console
python3 -m pip install -r docs/requirements.txt
sphinx-build -b html docs/ docs/_build/
```

This will produce the html version of the documentation which you can navigate by opening `docs/_build/index.html`.

If you have any touble building the docs, don't hesitate to open an issue to request help or simply provide the content you would like to add in markdown if that is simpler for you.

## Sphinx / reStructuredText (reST)

The markup language used for the Mila Docs is [reStructuredText](http://docutils.sourceforge.net/rst.html) and we follow the [Python’s Style Guide for documenting](https://docs.python.org/devguide/documenting.html#style-guide).

Here are some of reST syntax useful to know (more can be found in [Sphinx's reST Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)):

### Inline markup

* one asterisk: `*text*` for emphasis (italics),
* two asterisks: `**text**` for strong emphasis (boldface), and
* backquotes: ` ``text`` ` for code samples, and
* external links: `` `Link text <http://target>`_ ``.

### Lists

```reST
* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues
```

### Sections

```reST
=================
This is a heading
=================
```

There are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, the Python documentation is suggesting the following convention:

    * `#` with overline, for parts
    * `*` with overline, for chapters
    * `=`, for sections
    * `-`, for subsections
    * `^`, for subsubsections
    * `"`, for paragraphs

### Note box

```reST
.. note::
   This is a long
   long long note
```