Metadata-Version: 2.1
Name: superhelp
Version: 0.9.15
Summary: SuperHELP - Help for Humans!
Home-page: https://git.nzoss.org.nz/pyGrant/superhelp
Author: Grant Paton-Simpson
Author-email: grant@p-s.co.nz
License: MIT
Download-URL: https://git.nzoss.org.nz/pyGrant/superhelp/dist/superhelp-0.9.15.tar.gz
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: Markdown (>=3.2.1)
Requires-Dist: PyYAML (>=5.3.1)
Requires-Dist: Pygments (>=2.6.1)
Requires-Dist: astpath (>=0.9.0)
Requires-Dist: cssselect (>=1.1.0)
Requires-Dist: flake8 (>=3.5)
Requires-Dist: lxml (>=4.5.0)
Requires-Dist: tabulate (>=0.8.7)

# https://git.nzoss.org.nz/pyGrant/superhelp

version number: 0.9.15
author: Grant Paton-Simpson

## Overview

Superhelp is Help for Humans! The goal is to provide customised help for
simple code snippets. Superhelp is not intended to replace the built-in Python
help but to supplement it for basic Python code structures. Superhelp will
also be opinionated. Help can be provided in a variety of contexts including
the terminal and web browsers (perhaps as part of on-line tutorials).

## Quick Start

Click the button below to open a Binder Jupyter Notebook you can play around
in e.g. get advice on a line or snippet of Python

[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/git/https%3A%2F%2Fgit.nzoss.org.nz%2FpyGrant%2Fsuperhelp.git/master?filepath=notebooks%2FSuperhelpDemo.ipynb)

## Installation

Note - Python 3.6+ only. If you have an older version of Python use the Binder
Jupyter Notebook button instead (see higher up)

To install

1) Use pip e.g.

    $ pip3 install superhelp

or similar

    $ python3 -m pip install superhelp

2) Or clone the repo

    $ git clone https://git.nzoss.org.nz/pyGrant/superhelp.git
    $ python3 setup.py install

## Example Use Cases

* Charlotte is a Python beginner and wants to get advice on a five-line
function she wrote to display greetings to a list of people. She learns about
Python conventions for variable naming and better ways of combining strings.

* Avi wants to get advice on a named tuple. He learns how to add doc strings
to individual fields.

* Zach is considering submitting some code to Stack Overflow but wants to
improve it first (or possibly get ideas for a solution directly). He discovers
that a list comprehension might work. He also becomes aware of dictionary
comprehensions for the first time.

* Noor has written a simple Python decorator but is wanting to see if there is
anything which can be improved. She learns how to use functool.wrap from an
example provided.

* Al is an experienced Python developer but tends to forget things like doc
strings in his functions. He learns a standard approach and starts using it
more often.

# Example Usage

## Screenshot from HTML

![Example HTML output](https://git.nzoss.org.nz/pyGrant/superhelp/-/raw/master/example_html_output_1.png)

## Screenshot from Terminal

![Example Terminal output](https://git.nzoss.org.nz/pyGrant/superhelp/-/raw/master/example_terminal_output_1.png)

## Notebook

Add new cell at end with content like:

    %%shelp

    def sorted(my_list):
        sorted_list = my_list.sort()
        return sorted_list

and run it to get advice.

The notebook has more detailed instructions at the top.

## Local Installation

    $ shelp -h  ## get help on usage

    $ shelp --snippet "people = ['Tomas', 'Sal', 'Raj']" --displayer html --level Main
    $ shelp -s "people = ['Tomas', 'Sal', 'Raj']" -d html -l Main

    $ shelp --file-path my_snippet.py --displayer cli  --level Extra
    $ shelp -f snippet1.txt -d cli -l Brief

    $ shelp  ## to see advice on an example snippet displayed (level Extra)


## Stretch Ideas

* Extend beyond standard library into popular libraries like requests, bottle, flask etc.


