This is the Home of your awesome `python` projects' Documentation. 

# Projects

* [Example Project](/example_project) - Super project

# About

This Documentation has 2 layers:

* Each Python Project listed above has its own documentation, independantly generated _via_ [Sphinx](http://www.sphinx-doc.org/en/master/), especially thanks to `autodoc` which generates documentation from docstrings in the source code
</br></br>

* On top of these Project Documentations is the present Home Documentation which you are reading. It is generated by [Mkdocs](http://www.mkdocs.org) and is used to explore projects and store general, shared Documentation accross projects


# How to Use

## mkdocs

    mkdocs.yml    # The configuration file for mkdocs.
    docs/
        index.md  # The documentation homepage (this one).
        ...       # Other markdown pages, images and other files. Standard mkdocs.

!!! important
    `index.md` **has** to have a section "# Projects"

## Adding a new project to the list

This procedure is independant from the presence of code in your project (_i.e._ whether or not it is already started or not yet). It is also independant from the presence of Documenation. See [Write Sphinx Documentation](documentation) for that matter. 

To list a new project in the *Projects* section:

1. Add it at the root of this Home Documentation (where `docs/` and `mkdocs.yml` are)
2. Add a specific empty file to it : `touch my_awesome_project/__project__`
3. Mention it in this file's (`index.md`) [Projects](#projects) section as follows:
```
    * [My Project](/my_awesome_project) - My Project's short description`
```

!!! note 
    `my_awesome_project` is the name of the folder your project is in, and the `/` is mandatory

## Built-in Server

Running `mkinx serve` will start a local http server for you to browse your documentation. If you don't want to use the default port (`8443`), use the `serve_port` flag: `mkinx serve -s 7777`

!!! note "Changes"
    `mkinx` tracks changes and modifications in `.md` or `.rst` files: it will automatically trigger a build to update the html files. Sweet!

## Building the Documentations

You don't have to do much but `mkinx build` with some flags:

```
$ mkinx -h
usage: mkinx [-h] [--version] [-v] [-A] [-F] [-o]
             [-p [PROJECTS [PROJECTS ...]]] [-s [SERVE_PORT]]
             [{init,build,serve,}] [project_name]

Building Doc

positional arguments:
  {init,build,serve,}   Available commands for mkinx
  project_name          [init] Your project's name

optional arguments:
  -h, --help            show this help message and exit
  --version             Print mkinx's version
  -v, --verbose         [build] verbose flag (Sphinx will stay verbose)
  -A, --all             [build] Build doc for all projects
  -F, --force           [build] force the build, no verification asked
  -o, --only_index      [build] only build projects listed in the
                        Documentation's Home
  -p [PROJECTS [PROJECTS ...]], --projects [PROJECTS [PROJECTS ...]]
                        [build] list of projects to build
  -s [SERVE_PORT], --serve_port [SERVE_PORT]
                        [serve] the server's port, defaults to 8443
```

`mkinx build` does 3 things:

1. Build your projects' documentations by running `make html` in the relevant projects (according to the listed projects if you use `-p` or `-A` flags)
2. Update your projects' documentations' `index.html` files to add a link back here
3. Build `mkdoc`'s home documentation, _i.e._ this very document and others as parametered in `mkdocs.yml`

A couple examples:

* To build a new project's documentation but leave others untouched:
    * `python build.py -p my_awesome_project`
    * Obviously works to rebuild it every time it is updated
* To build documentations for all projects which are listed in [Projects](#projects):
    * `python build.py -A -o`
    * There may be projects not listed above for any reason and you may not want to build their documentation, hence the `-o` flag

## Configuration

### Home Documentation: `mkdocs`

Explore the `mkdocs.yml` file to configure your Home Documentation. Here are the keys:

* `site_name:The name you want to give to this Home Documentation`.
* `pages:` is a list of the pages available, listed on the sidebar
    * items in this list are `- page's title: file.md`
* `theme:readthedocs`
* `markdown_extensions:` is a list of extensions to use. they are listed [here](https://python-markdown.github.io/extensions/#officially-supported-extensions)
    * `- admonition` allows for reStructuredText-style admonition, that is the "important", "note" and "danger" colored boxes

### Projects' Documentations: `sphinx`

In your project's `source` directory lies the source files for `sphinx` to generate your documentation. As for the Home Documentation you should explore the `conf.py` file in this `source` directory to set this particular project's configuration. 