Metadata-Version: 2.1
Name: examples
Version: 0.1.0
Summary: Tests and Documentation Done by Example.
License: MIT
Author: Timothy Crosley
Author-email: timothy.crosley@gmail.com
Requires-Python: >=3.6,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Dist: pydantic (>=0.32.2,<0.33.0)
Description-Content-Type: text/markdown

[![eXamples - Python Tests and Documentation Done by Example.](https://raw.github.com/timothycrosley/examples/master/art/logo_large.png)](https://timothycrosley.github.io/examples/)
_________________

[![PyPI version](https://badge.fury.io/py/examples.svg)](http://badge.fury.io/py/examples)
[![Build Status](https://travis-ci.org/timothycrosley/examples.svg?branch=master)](https://travis-ci.org/timothycrosley/examples)
[![codecov](https://codecov.io/gh/timothycrosley/examples/branch/master/graph/badge.svg)](https://codecov.io/gh/timothycrosley/examples)
[![Join the chat at https://gitter.im/timothycrosley/examples](https://badges.gitter.im/timothycrosley/examples.svg)](https://gitter.im/timothycrosley/examples?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![License](https://img.shields.io/github/license/mashape/apistatus.svg)](https://pypi.python.org/pypi/examples/)
[![Downloads](https://pepy.tech/badge/examples)](https://pepy.tech/project/examples)
_________________

[Read Latest Documentation](https://timothycrosley.github.io/examples/) - [Browse GitHub Code Repository](https://github.com/timothycrosley/examples/)
_________________

**eXamples** (AKA: xamples for SEO purposes) is a Python3 library enabling interactable, self-documentating, and self-verifying examples to be attached to Python functions using decorators.

[![Example Usage Gif](https://raw.githubusercontent.com/timothycrosley/portray/master/art/example.gif)](https://raw.githubusercontent.com/timothycrosley/portray/master/art/example.gif)

Key Features:

* **Simple and Obvious API**: Simply add `@examples.example(*args, **kwargs)` decorators for each example you want to add to a function.
* **Statically Generated**: `portray` websites are easy to host on GitHub pages and other similar services as they are outputted as standard static HTML websites.
* **Markdown Aware**: `portray` will automatically include your projects `.md` files and render them into HTML. It will also find and render Markdown within `__doc__` strings.
* **Fully Configurable**: While `portray` doesn't have to be configured, you still can fully configure it within the standard `pyproject.toml` file.
* **Easily Programmable**: `portray` exposes a clean and simple [Python API](https://timothycrosley.github.io/portray/reference/portray/api/).
* **Searchable**: Out of the box `portray` makes all of your documentation, even autogenerated code references, free-text searchable.
* **Themeable**: `portray` is compatible with all existing [MkDocs Themes](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes).

Under the hood, portray combines the [Markdown](https://commonmark.org/help/) documentation rendering capabilities provided by [MkDocs](https://www.mkdocs.org/)
with the automatic reference documentation generated by [pdocs](https://timothycrosley.github.io/pdocs/).

## Quick Start

The following guides should get you up and running with a documentation website in no time.

1. [Installation](https://timothycrosley.github.io/portray/docs/quick_start/1.-installation/) - TL;DR: Run `pip3 install portray` within your projects virtual environment.
2. [Command Line Usage](https://timothycrosley.github.io/portray/docs/quick_start/2.-cli/) - TL;DR: Run `portray in_browser` to test and `portray on_github_pages` to deploy.
3. [API Usage](https://timothycrosley.github.io/portray/docs/quick_start/3.-api/) - TL;DR: Everything available via the CLI is also easily available programmatically from within Python.
4. [Configuration](https://timothycrosley.github.io/portray/docs/quick_start/4.-configuration/) - TL;DR: Put all configuration within a `[tool.portray]` section of your `pyproject.toml` file.

## Why Create Examples?

I've always wanted a way to attach examples to functions in a way that would be re-useable for documentation, testing, and API proposes.
Just like moving Python parameter types from comments into prorammatically specified and easily introspectable entities has made them more braodly useful,
I hope examples can do the same for example parameters.

I hope you too find `eXamples` useful!

~Timothy Crosley

