Metadata-Version: 2.1
Name: mkdocs-autoapi
Version: 0.1.6
Summary: MkDocs plugin providing automatic API reference generation
Author-email: Jacob Ayers <jcayers20@gmail.com>
Project-URL: Repository, https://github.com/jcayers20/mkdocs-autoapi
Project-URL: Issues, https://github.com/jcayers20/mkdocs-autoapi/issues
Project-URL: License, https://github.com/jcayers20/mkdocs-autoapi/blob/main/LICENSE
Keywords: mkdocs,documentation,api,autoapi
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs>=1.4.0
Requires-Dist: mkdocstrings>=0.19.0
Provides-Extra: crystal
Requires-Dist: mkdocstrings-crystal>=0.3.4; extra == "crystal"
Provides-Extra: python-legacy
Requires-Dist: mkdocstrings-python-legacy>=0.2.1; extra == "python-legacy"
Provides-Extra: python
Requires-Dist: mkdocstrings-python>=0.5.2; extra == "python"

# mkdocs-autoapi

## Description

`mkdocs-autoapi` is a MkDocs plugin that automatically generates API
documentation from your project's source code. The idea for the plugin comes
from this [recipe](https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages)
in the MkDocs documentation.

## Installation

### Requirements

* Python version 3.6 or higher
* MkDocs version 1.4.0 or higher
* mkdocstrings version 0.19.0 or higher

### Installation via `pip`

We recommend installing this package with `pip`:

```bash
pip install mkdocs-autoapi
```

## Usage

### Basic Usage

To use the plugin, add the following configuration to your `mkdocs.yml` file:

```yaml
plugins:
  - ... other plugin configuration ...
  - mkdocs-autoapi
  - mkdocstrings
```

### Setting the Project Root

By default, the plugin will use the current working directory as the project
root. If you would like to use a different directory, you can specify a value
in the `project_root` configuration option:

```yaml
plugins:
  - ... other plugin configuration ...
  - mkdocs-autoapi:
      project_root: /path/to/project/root
  - mkdocstrings
```

### Excluding Patterns

You can exclude files and directories from the documentation by specifying a
value in the `exclude` configuration option. This option accepts a list of
glob patterns. Note that the following patterns are always excluded:

* `**/.venv/**/`
* `**/venv/**/`

As an example, suppose your project has the following structure:

```tree
project/
    docs/
        index.md
    module/
        __init__.py
        lorem.py
        ipsum.py
        dolor.py
    second_module/
        __init__.py
        lorem.py
        sit.py
        amet.py
    venv/
    mkdocs.yml
    README.md
```

To exclude all files named `lorem.py`, you can add the following configuration
to your `mkdocs.yml` file:

```yaml
plugins:
  - ... other plugin configuration ...
  - mkdocs-autoapi:
      exclude:
        - "**/lorem.py"
  - mkdocstrings
```

## Contributing

Contributions are always welcome! Please submit a pull request or open an issue
to get started.

## License

This project is licensed under the MIT License. See the [LICENSE](https://github.com/jcayers20/mkdocs-autoapi/blob/main/LICENSE) file
for more information.
