Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (testpypi.python.org).
Help us improve Python packaging - Donate today!

An open source license where clients give back by sharing hard-earned knowledge about the source code.

Project Description
# WriteLeft

**It take a village to properly document a software project.**

WriteLeft is an open source license where clients give back by sharing hard-earned knowledge about the source code.
Strike up a spirit of knowledge sharing by including a WriteLeft license in your code!

## Who should use a WriteLeft license?

WriteLeft was designed for researchers who want to share research code that is still rough around the edges.
Our philosophy is that programmers often need to use rough code, and usually learn a lot about it along the way.
The WriteLeft license is designed to lower the threshold to sharing found knowledge about code.
Ultimately, we believe that this will lead to greater use and maintenance of code that would otherwise be neglected and forgotten.

We are inspired to
make it easy to make substantial yet micro-sized knowledge contributions,
ask for help predictably and infrequently,
and to reliably detect genuine discoveries about the code.

## Enabling a WriteLeft license

WriteLeft is an **active license**.
Within reason, it reminds users to contribute at the moments they're most fit to.
As this is an active license, first, install WriteLeft as a dependency.

pip install writeleft

Then, enable it by wrapping your public API with WriteLeft.
First, initialize WriteLeft with a reference to a GitHub repository, where knowledge contributions will be directed.

from writeleft import WriteLeft

wl = WriteLeft({
'owner': <GitHub owner name>,
'repository': <GitHub owner name>,
})

Then, encouraging micro-contributions is as simple as calling the `collect` function on your module.
We recommend doing this in your `__init__.py` file where you make all of the public functionality available.

import my_module
wl.collect(my_module)

Behind the scenes, WriteLeft adds a light wrapper around all of the public methods and classes of your module.
The first time someone calls that method or class, they will be asked to share their knowledge about what that method or class does.

By default, each client will be asked to make a maximum of three contributions.
To change this, you can set the `max_contributions` parameter in the `WriteLeft` constructor.

wl = WriteLeft({
'owner': <GitHub owner name>,
'repository': <GitHub owner name>,
}, max_contributions=2)

### What will users see?

WriteLeft has been designed to elicit useful information with only a minimum of required effort from a user.
Let's say I'm a user who has just imported the function `foo` from your package.

from your_module import foo
result = foo(1, 2)

The first time I execute this code, I (your user) will see this prompt.

I'm WriteLeft, a license all about sharing programming knowledge. I'm here
to ask you a few questions about this code (3 max). This is to help
collect a common base of knowledge for you and others to reference later.

I see you just called `foo` with the arguments (1, 2).
Can you tell me, What does `foo` do?

>

Here, I would take a few seconds to write a sentence or two about what `foo` does.

> Foo takes in two arguments, multiplies them together, and adds two.

I submit it, and this is formatted into a Docstrings-style piece of reference documentation.
This reference documentation is then submitted as a pull request to your project's README.

### What kinds of documentation can this create?

We hope that WriteLeft documentation will eventually cover installation instructions, lightweight reference documentation, and bug workarounds.
Check back for an example of the documentation that WriteLeft generates in the near future.

## Advanced Usage

You can disable the collection of knowledge for specific members of your module by passing these members as a list to the `exclude` parameter to the `collect` method.

import my_module
from my_module import forgotten_function, ColdShoulderedClass

wl.collect(
my_module,
exclude=[forgotten_function, ColdShoulderedClass],
)

## Contributing

Developing this package requires Python version 3.4 or higher to support the `unwrap` command in the unit tests.

### Running tests

python -m unittest discover -s tests

### Distributing

python setup.py bdist_wheel
twine register dist/<.whl file> # Look to see what .whl file was generated by the first step
twine upload dist/<.whl file>

## Why is it called "WriteLeft"?

WriteLeft is a play on words based on the idea of [*Copyleft*](https://www.gnu.org/licenses/copyleft.en.htm://www.gnu.org/licenses/copyleft.en.html).
Copyleft licenses ensure that modified and extended versions of a program preserve the same freedoms.
A WriteLeft license ensures that clients of software work together to promote everyone's ability to learn and solve problems with the *written* knowledge about a software project.

Copyleft licenses are largely responsible for today's large, high-quality open source projects.
WriteLeft licenses turn their attention to one of the major challenges in today's global, massively distributed software development:
making the genuinely useful, small, resource-strapped project thrive with the help of a small community.
Release History

Release History

This version
History Node

0.0.7

History Node

0.0.6

History Node

0.0.5

History Node

0.0.4

History Node

0.0.1

History Node

0.0.0

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
writeleft-0.0.7-py3-none-any.whl (12.4 kB) Copy SHA256 Checksum SHA256 py3 Wheel Nov 14, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting