# -*- coding: utf-8 -*-
from setuptools import setup

package_dir = \
{'': 'src'}

packages = \
['settings_doc']

package_data = \
{'': ['*'], 'settings_doc': ['templates/*']}

install_requires = \
['Jinja2>=3.0.2,<4.0.0',
 'pydantic>=1.8.2,<2.0.0',
 'termcolor>=1.1.0,<2.0.0',
 'typer[all]>=0.4.0,<0.5.0']

entry_points = \
{'console_scripts': ['settings-doc = settings_doc.main:app']}

setup_kwargs = {
    'name': 'settings-doc',
    'version': '0.5.1',
    'description': 'A command line tool for generating Markdown documentation and .env files from pydantic BaseSettings.',
    'long_description': '<h1 align="center" style="border-bottom: none;">⚙&nbsp;📝&nbsp;&nbsp;Settings&nbsp;DocGen&nbsp;&nbsp;📝&nbsp;⚙</h1>\n<h3 align="center">A command line tool for generating Markdown documentation and .env files from <a href="https://pydantic-docs.helpmanual.io/usage/settings">pydantic.BaseSettings</a>.</h3>\n\n<p align="center">\n    <img alt="CircleCI" src="https://img.shields.io/circleci/build/github/radeklat/settings-doc">\n    <img alt="Codecov" src="https://img.shields.io/codecov/c/github/radeklat/settings-doc">\n    <img alt="GitHub tag (latest SemVer)" src="https://img.shields.io/github/tag/radeklat/settings-doc">\n    <img alt="Maintenance" src="https://img.shields.io/maintenance/yes/2021">\n    <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/radeklat/settings-doc">\n    <img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/settings-doc">\n    <img alt="PyPI - License" src="https://img.shields.io/pypi/l/settings-doc">\n    <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/settings-doc">\n</p>\n\nThe same way you are able to generate OpenAPI documentation from [`pydantic.BaseModel`](https://pydantic-docs.helpmanual.io/usage/models/), `settings-doc` allows you to generate documentation from [`pydantic.BaseSettings`](https://pydantic-docs.helpmanual.io/usage/settings).\n\nIt is powered by the [Jinja2](https://jinja.palletsprojects.com/en/latest/) templating engine and [Typer](https://typer.tiangolo.com/) framework. If you don\'t like the built-in templates, you can easily modify them or write completely custom ones. All attributes of the [`BaseSettings`](https://pydantic-docs.helpmanual.io/usage/settings) models are exposed to the templates.\n\n<!--\n    How to generate TOC from PyCharm:\n    https://github.com/vsch/idea-multimarkdown/wiki/Table-of-Contents-Extension\n-->\n[TOC levels=1,2 markdown formatted bullet hierarchy]: # "Table of content"\n\n# Table of content\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Minimal example](#minimal-example)\n  - [Adding more information](#adding-more-information)\n  - [Updating existing documentation](#updating-existing-documentation)\n  - [Custom templates](#custom-templates)\n  - [Custom settings attributes in templates](#custom-settings-attributes-in-templates)\n- [Features overview](#features-overview)\n  - [Markdown](#markdown)\n  - [.env](#env)\n\n# Installation\n\n```\npip install settings-doc\n```\n\n# Usage\n\nSee `settings-doc --help` for all options.\n\n## Minimal example\n\nLet\'s assume the following [`BaseSettings`](https://pydantic-docs.helpmanual.io/usage/settings) in `src/settings.py` of a project:\n\n```python\nfrom pydantic import BaseSettings\n\nclass AppSettings(BaseSettings):\n    logging_level: str\n```\n\nYou can generate a Markdown documentation into stdout with:\n\n```shell script\nsettings-doc generate --class src.settings.AppSettings --output-format markdown\n```\n\nWhich will output:\n\n```markdown\n# `LOGGING_LEVEL`\n\n**Required**\n```\n\nSimilarly, you can generate a `.env` file for local development with:\n\n```shell script\nsettings-doc generate --class src.settings.AppSettings --output-format dotenv\n```\n\nWhich will output:\n\n```dotenv\nLOGGING_LEVEL=\n\n```\n\n## Adding more information\n\nYou can add any extra field parameters to the settings. By default, `settings-doc` will utilise the default value, whether the parameter is required or optional, description, example value and list of possible values:\n\n```python\nfrom pydantic import BaseSettings, Field\n\nclass AppSettings(BaseSettings):\n    logging_level: str = Field(\n        "WARNING",\n        description="Log level.",\n        example="`WARNING`",\n        possible_values=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],\n    )\n```\n\nWhich will generate the following markdown:\n\n```markdown\n# `LOGGING_LEVEL`\n\n*Optional*, default value: `WARNING`\n\nLog level.\n\n## Examples\n\n`WARNING`\n\n## Possible values\n\n`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`\n```\n\nor `.env` file:\n\n```dotenv\n# Log level.\n# Possible values:\n#   `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`\n# LOGGING_LEVEL=WARNING\n```\n\n## Updating existing documentation\n\nYou may want to generate the documentation into and existing document. To fit with the heading structure, you can adjust the heading levels with `--heading-offset`. Additionally, you can specify the location where to generate the documentation with two marks set by `--between <START MARK> <END MARK>`.\n\nLet\'s assume your `README.md` looks like this:\n\n```markdown\n# My app\n\nThis app is distributes as a docker image and configurable via environment variables. See the list below:\n\n<!-- generated env. vars. start -->\n<!-- generated env. vars. end -->\n```\n\nWhen you run:\n\n```shell script\nsettings-doc generate \\\n  --class src.settings.AppSettings \\\n  --output-format markdown \\ \n  --update README.md \\\n  --between "<!-- generated env. vars. start -->" "<!-- generated env. vars. end -->" \\\n  --heading-offset 1\n```\n\nthe updated `README.md` will get only the specified location overwritten:\n\n```markdown\n# My app\n\nThis app is distributes as a docker image and configurable via environment variables. See the list below:\n\n# Environment variables\n<!-- generated env. vars. start -->\n## `LOGGING_LEVEL`\n\n*Optional*, default value: `WARNING`\n\nLog level.\n\n### Examples\n\n`WARNING`\n\n### Possible values\n\n`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`\n<!-- generated env. vars. end -->\n```\n\n## Custom templates\n\n`settings-doc` comes with a few built-in templates. You can override them or write completely new ones.\n\nTo just modify the existing ones:\n1. Copy the built-in templates into a new directory:\n   ```shell script\n   mkdir custom_templates\n   settings-doc templates --copy-to custom_templates\n   ```\n2. Modify the template copies in `custom_templates` to suit your needs. You can keep only the modified ones as `settings-doc` always falls back to the built-in ones.\n3. Use them when generating the documentation:\n   ```shell script\n   settings-doc generate \\\n     --class src.settings.AppSettings \\\n     --output-format dotenv \\\n     --templates custom_templates\n   ```\n\nTo create new ones, create a folder and then a Jinja2 template with a file names `<OUTPUT_FORMAT>.jinja`. Then simply reference both in the command line options:\n\n```shell script\nmkdir custom_templates\n\necho "{{ field.title }}" > custom_templates/only_titles.jinja\n\nsettings-doc generate \\\n --class src.settings.AppSettings \\\n --output-format only_titles \\\n --templates custom_templates\n```\n\n## Custom settings attributes in templates\n\nBy default, there are several variables available in all templates:\n- `heading_offset`, which is the value of the `--heading-offset` option, defaults to `0`.\n- `fields`, which is the value of `BaseSettings.__fields__.values()`. In other words, a list of individual settings fields. Each field is then an instance of [`ModelField`](https://github.com/samuelcolvin/pydantic/blob/master/pydantic/fields.py).\n\nExtra parameters unknown to pydantic are stored in `field.field_info.extra`. Examples of such parameters are `example` and `possible_values`.\n\nEven the bare `ModelField` without any extra parameters has a large number of attributes. To see them all, run this `settings-doc` with `--format debug`.\n\n# Features overview\n\n- Output into several formats with `--output-format`: markdown, dotenv\n- Writes into stdout by default, which allows piping to other tools for further processing.\n- Able to update specified file with `--update`, optionally between two given string marks with `--between`. Useful for keeping documentation up to date.\n- Additional templates and default template overrides via `--templates`.\n\n## Markdown\n\n- Allows setting a `--heading-offset` to fit into existing documentation.\n- Intelligently formats example values as:\n  - Single line if all values fit withing 75 characters.\n  - List of values if all values won\'t fit on a single line.\n  - List of `<VALUE>: <DESCRIPTION>` if example values are tuples of 1-2 items.\n\n## .env\n\n- Leaves environment variables commented if they have a default value as the app doesn\'t require them.',
    'author': 'Radek Lát',
    'author_email': 'radek.lat@gmail.com',
    'maintainer': None,
    'maintainer_email': None,
    'url': 'https://github.com/radeklat/settings-doc',
    'package_dir': package_dir,
    'packages': packages,
    'package_data': package_data,
    'install_requires': install_requires,
    'entry_points': entry_points,
    'python_requires': '>=3.6.2,<4.0.0',
}


setup(**setup_kwargs)
