# Project documentation

[TOC]

## pdoc

pdoc is a package that can produce automatically documentation for functions, classes etc from the DOCSTRINGS.

### install

pip3 install pdoc3

### run

`pdoc` includes a feature-rich "binary" program for producing HTML and plain text documentation of your modules. For example, to produce HTML documentation of your whole package in subdirectory 'build' of the current directory, using the default HTML template, run:

$ pdoc --html --output-dir build my_package

This will build the documentation for the python files in the ```my_package``` directory in the ```build/``` folder in HTML format.

If you want to omit the source code preview, run:

$ pdoc --html --config show_source_code=False my_package

For markdown output

$ pdoc --PDF build >> markdownFile.md

To override the built-in HTML/CSS and plain text templates, copy the relevant templates from `pdoc/templates` directory into a directory of your choosing and edit them. When you run [pdoc command](https://pdoc3.github.io/pdoc/doc/pdoc/#command-line-interface) afterwards, pass the directory path as a parameter to the `--template-dir` switch.

To run a local HTTP server while developing your package or writing docstrings for it, run:

$ pdoc --http : my_package

To re-build documentation as part of your continuous integration (CI) best practice, i.e. ensuring all reference links are correct and up-to-date, make warnings error loudly by settings the environment variable [`PYTHONWARNINGS`](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONWARNINGS) before running pdoc:

$ export PYTHONWARNINGS='error::UserWarning'

For brief usage instructions, type:

$ pdoc --help

Even more usage examples can be found in the [FAQ](https://github.com/pdoc3/pdoc/issues?q=is%3Aissue+label%3Aquestion).

## Mkdocs

Mkdocs is a suite that can generate documentation in HTML from a list of markdown files. It does not get documentation from DocStrings. For this, use pdoc.

### install

Install the `mkdocs` package using pip:

pip install mkdocs

### run

Getting started is super easy. CD into the folder containing the project and type

mkdocs new .

Take a moment to review the initial project that has been created for you.


There's a single configuration file named `mkdocs.yml`, and a folder named `docs` that will contain your documentation source files. Right now the `docs` folder just contains a single documentation page, named `index.md`.

### server

MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the `mkdocs.yml` configuration file, and then start the server by running the `mkdocs serve` command:

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes

Open up `http://127.0.0.1:8000/` in your browser, and you'll see the default home page being displayed

### adding pages

Now add a second page to your documentation:

curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

As our documentation site will include some navigation headers, you may want to edit the configuration file and add some information about the order, title, and nesting of each page in the navigation header by adding a [`nav`](https://www.mkdocs.org/user-guide/configuration/#nav) setting:

site_name: MkLorum
nav:
    - Home: index.md
    - About: about.md

Save your changes and you'll now see a navigation bar with `Home` and `About` items on the left as well as `Search`, `Previous`, and `Next` items on the right.

### themes

Now change the configuration file to alter how the documentation is displayed by changing the theme. Edit the `mkdocs.yml` file and add a [`theme`](https://www.mkdocs.org/user-guide/configuration/#theme) setting:

site_name: MkLorum
nav:
    - Home: index.md
    - About: about.md
theme: readthedocs

Save your changes, and you'll see the ReadTheDocs theme being used.

### build

That's looking good. You're ready to deploy the first pass of your `MkLorum` documentation. First build the documentation:

mkdocs build

This will create a new directory, named `site`. Take a look inside the directory:

$ ls site
about  fonts  index.html  license  search.html
css    img    js          mkdocs   sitemap.xml

Notice that your source documentation has been output as two HTML files named `index.html` and `about/index.html`. You also have various other media that's been copied into the `site` directory as part of the documentation theme. You even have a `sitemap.xml` file and `mkdocs/search_index.json`.

If you're using source code control such as `git` you probably don't want to check your documentation builds into the repository. Add a line containing `site/` to your `.gitignore` file.

echo "site/" >> .gitignore

If you're using another source code control tool you'll want to check its documentation on how to ignore specific directories.

After some time, files may be removed from the documentation but they will still reside in the `site` directory. To remove those stale files, just run `mkdocs` with the `--clean` switch.

mkdocs build --clean

## Sphinx

### Install

Assuming you have Python already, [install Sphinx](https://www.sphinx-doc.org/en/master/usage/installation.html):

pip install sphinx

Create a directory inside your project to hold your docs:

cd /path/to/project
mkdir docs

Run `sphinx-quickstart` in there:

cd docs
sphinx-quickstart

this will create a ```source/``` folder. In addition, this quick start will walk you through creating the basic configuration; in most cases, you can just accept the defaults. When it’s done, you’ll have an `index.rst`, a `conf.py` and some other files. Add these to revision control.

### build

Now, edit your `index.rst` and add some information about your project. Include as much detail as you like (refer to the [reStructuredText syntax](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) or [this template](https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#id1) if you need help). Build them to see how they look:

make html

Your `index.rst` has been built into `index.html` in your documentation output directory (typically `_build/html/index.html`). Open this file in your web browser to see your docs.

### markdown

Install ```recommonmark``` by running:

pip install --upgrade recommonmark

Edit ```conf.py``` in the ```source/``` directory and edit the ```extensions = [....]``` line the as follows:

extensions = ['recommonmark'
]