# Tutorials

## Setting up Automatic API Documentation Generation

This tutorial will assume that you already have a basic Sphinx project set up. If you are not sure how to do this, you can follow the sphinx:usage/quickstart guide in the Sphinx documentation.

The recommended way of installing AutoAPI is through a virtualenv. Once you have a virtualenv set up, you can install AutoAPI with the command:

Language | Command
--- | ---
Python | `pip install sphinx-autoapi`
Go | `pip install sphinx-autoapi[go]`
Javascript | `pip install sphinx-autoapi`
.NET | `pip install sphinx-autoapi[dotnet]`

Depending on which language you are trying to document, each language has a different set of steps for finishing the setup of AutoAPI:

- Python

- Go

- Javascript

- .NET

### Python

To enable the extension, we need to add it to the list of extensions in Sphinx’s `conf.py` file:

    extensions = ['autoapi.extension']

For Python, there is only one required configuration option that we need to set. `autoapi_dirs` tells AutoAPI which directories contain the source code to document. These can either be absolute, or relative to the source directory of your documentation files. For example, say we have a package and we have used `sphinx-quickstart` to create a Sphinx project in a `docs/` folder. The directory structure might look like this:

    mypackage/
    ├── docs
    │   ├── _build
    │   ├── conf.py
    │   ├── index.rst
    │   ├── make.bat
    │   ├── Makefile
    │   ├── _static
    │   └── _templates
    ├── mypackage
    │   ├── _client.py
    │   ├── __init__.py
    │   └── _server.py
    └── README.md

`sphinx-quickstart` sets up the `sphinx-build` to run from inside the `docs/` directory, and the source code is one level up. So the value of our `autoapi_dirs` option would be:

    autoapi_dirs = ['../mypackage']

If you are documenting many packages, you can point AutoAPI to the directory that contains those packages. For example if our source code was inside a `src/` directory:

    mypackage/
    ├── docs
    │   ├── _build
    │   ├── conf.py
    │   ├── index.rst
    │   ├── make.bat
    │   ├── Makefile
    │   ├── _static
    │   └── _templates
    ├── README.md
    └── src
        └── mypackage
            ├── _client.py
            ├── __init__.py
            └── _server.py

We can configure `autoapi_dirs` to be:

    autoapi_dirs = ['../src']

Now that everything is configured, AutoAPI will generate documentation when you run Sphinx!

    cd docs/
    sphinx-build -b html . _build

### Go

Support for Go requires you to have the go environment installed (https://golang.org/dl/), as well as our godocjson tool:

    go get github.com/readthedocs/godocjson

and the Go domain extension for Sphinx:

    pip install sphinxcontrib-golangdomain

To enable the AutoAPI extension, we need to add it to the list of extensions in Sphinx’s `conf.py` file with the Go domain extension:

    extensions = [
        'sphinxcontrib.golangdomain',
        'autoapi.extension',
    ]

For Go, there are two required configuration options that we need to set. `autoapi_type` tells AutoAPI what type of language we are documenting. For Go, this is:

    autoapi_type = 'go'

The second configuration option is `autoapi_dirs`, which tells AutoAPI which directories contain the source code to document. These can either be absolute, or relative to the source directory of your documentation files. So if your documentation was inside a `docs/` directory and your source code is in an `example` directory one level up, you would configure `autoapi_dirs` to be:

    autoapi_dirs = ['../example']

Now that everything is configured, AutoAPI will generate documentation when you run Sphinx!

    cd docs/
    sphinx-build -b html . _build

### Javascript

Support for Javascript requires you to have jsdoc (http://usejsdoc.org/) installed:

    npm install jsdoc -g

To enable the AutoAPI extension, we need to add it to the list of extensions in Sphinx’s `conf.py` file:

    extensions = ['autoapi.extension']

For Javascript, there are two required configuration options that we need to set. `autoapi_type` tells AutoAPI what type of language we are documenting. For Javascript, this is:

    autoapi_type = 'javascript'

The second configuration option is `autoapi_dirs`, which tells AutoAPI which directories contain the source code to document. These can either be absolute, or relative to the source directory of your documentation files. So if your documentation was inside a `docs/` directory and your source code is in an `example` directory one level up, you would configure `autoapi_dirs` to be:

    autoapi_dirs = ['../example']

Now that everything is configured, AutoAPI will generate documentation when you run Sphinx!

    cd docs/
    sphinx-build -b html . _build

### .NET

Support for .NET requires you to have the docfx (https://dotnet.github.io/docfx/) tool installed, as well as the .NET domain extension for Sphinx:

    pip install sphinxcontrib-dotnetdomain

Firstly, we need to configure docfx to output to a directory known to AutoAPI. By default, `docfx` will output metadata files into the `_api` path. You can configure which path to output files into by setting the path in your docfx configuration file in your project repository. For example, if your documentation source files are located inside a `docs/` directory:

    {
      "metadata": [{
        "dest": "docs/_api"
      }]
    }

To enable the AutoAPI extension, we need to add it to the list of extensions in Sphinx’s `conf.py` file with the .NET domain extension:

    extensions = [
        'sphinxcontrib.dotnetdomain',
        'autoapi.extension',
    ]

For .NET, there are two required configuration options that we need to set. `autoapi_type` tells AutoAPI what type of language we are documenting. For .NET, this is:

    autoapi_type = 'dotnet'

The second configuration option is `autoapi_dirs`, which tells AutoAPI which directories contain the source code to document. These can either be absolute, or relative to the source directory of your documentation files. So if your documentation was inside a `docs/` directory and your source code is in an `example` directory one level up, you would configure `autoapi_dirs` to be:

    autoapi_dirs = ['../example']

Now that everything is configured, AutoAPI will generate documentation when you run Sphinx!

    cd docs/
    sphinx-build -b html . _build