examples 0.1.0

Read Latest Documentation - Browse GitHub Code Repository

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.

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.
• 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.

Under the hood, portray combines the Markdown documentation rendering capabilities provided by MkDocs with the automatic reference documentation generated by pdocs.

Quick Start

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

1. Installation - TL;DR: Run pip3 install portray within your projects virtual environment.
2. Command Line Usage - TL;DR: Run portray in_browser to test and portray on_github_pages to deploy.
3. API Usage - TL;DR: Everything available via the CLI is also easily available programmatically from within Python.
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