Documentation¶
All good projects have documentation - even if your program has help text.
At a minimum, you should detail any requirements and write instructions for installing, testing, and using a python package.
GitHub will always render the README.md
file on the landing page for your repository.
We suggest creating subsections for each of these topics in the file.
Requirements¶
1 2 3 | ## Requirements
Summarize runs on Python >= 3.6 and requires Numpy.
|
Installing¶
Pip can install from more places than just pypi and a local directory.
If you git add
, git commit
, and git push
all the files we created, you’ll be able to install summarize without a separate checkout command.
These directions show how users can install your package directly from your GitHub URL.
1 2 3 4 5 6 7 8 9 10 11 12 13 | ## Installing
Install with pip from master
```
$ pip install --user git+https://github.com/zyndagj/summarize.git
```
or a specific release
```
$ pip install --user git+https://github.com/zyndagj/summarize.git@release
```
|
Testing¶
It’s always a good idea to demonstrate how to both setup the test environment and run tests
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | ## Testing
Install test dependencies and run tests
```
$ git clone https://github.com/zyndagj/summarize.git
$ cd summarize
$ pip install --user .[dev]
# Run tests with tox
$ tox
# Run tests with pytest
$ pip install .
$ pytest
```
|
Usage¶
Lastly, include an explanation on usage along with expected output.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | ## Usage
```
usage: summarize [-h] [-N INT]
A simple tool for computing the mean of a random list
optional arguments:
-h, --help show this help message and exit
-N INT Number of random integers [5]
```
```
$ summarize -N 5
48.8
```
|