Including licences and writing READMEs

Sviluppare pacchetti Python

James Fulton

Climate informatics researcher

Why do I need a license?

  • To give others permission to use your code
Sviluppare pacchetti Python

Open source licenses

  • Find more information here
  • Allow users to
    • use your package
    • modify your package
    • distribute versions of your package
1 https://choosealicense.com
Sviluppare pacchetti Python

What is a README?

  • The "front page" of your package
  • Displayed on Github or PyPI
Sviluppare pacchetti Python

What to include in a README

README sections

  • Title
  • Description and Features
  • Installation
  • Usage examples
  • Contributing
  • License
Sviluppare pacchetti Python

README format

Markdown (commonmark)

  • Contained in README.md file
  • Simpler
  • Used in this course and in the wild
reStructuredText

  • Contained in README.rst file
  • More complex
  • Also common in the wild
Sviluppare pacchetti Python

Commonmark

Contents of README.md














`

What it looks like when rendered

Sviluppare pacchetti Python

Commonmark

Contents of README.md

# mysklearn

mysklearn is a package for complete 
**linear regression** in Python.


You can find out more about this package 
on [DataCamp](https://datacamp.com)

What it looks like when rendered

mysklearn

mysklearn is a package for complete linear regression in python.

You can find out more about this package on DataCamp

Sviluppare pacchetti Python

Commonmark

Contents of README.md

# mysklearn

mysklearn is a package for complete 
**linear regression** in Python.


You can find out more about this package 
on [DataCamp](https://datacamp.com)


## Installation
You can install this package using

What it looks like when rendered

mysklearn

mysklearn is a package for complete linear regression in python.

You can find out more about this package on DataCamp

Installation

You can install this package using

Sviluppare pacchetti Python

Commonmark

Contents of README.md

# mysklearn
mysklearn is a package for complete 
**linear regression** in Python.

You can find out more about this package 
on [DataCamp](https://datacamp.com)

## Installation
You can install this package using

```
pip install mysklearn
```

What it looks like when rendered

mysklearn

mysklearn is a package for complete linear regression in python.

You can find out more about this package on DataCamp

Installation

You can install this package using

pip install mysklearn
Sviluppare pacchetti Python

Adding these files to your package

Directory tree for package with subpackages

mysklearn/
|-- mysklearn
|   |-- __init__.py
|   |-- preprocessing
|   |   |-- ...
|   |-- regression
|   |   |-- ...
|   |-- utils.py
|-- setup.py
|-- requirements.txt
|-- LICENSE      <--- new files
|-- README.md    <--- added to top directory
Sviluppare pacchetti Python

MANIFEST.in

Lists all the extra files to include in your package distribution.

Sviluppare pacchetti Python

MANIFEST.in

Contents of MANIFEST.in

include LICENSE
include README.md

mysklearn/
|-- mysklearn
|   |-- __init__.py
|   |-- preprocessing
|   |   |-- ...
|   |-- regression
|   |   |-- ...
|   |-- utils.py
|-- setup.py
|-- requirements.txt
|-- LICENSE
|-- README.md
|-- MANIFEST.in   <---
Sviluppare pacchetti Python

Let's practice!

Sviluppare pacchetti Python

Preparing Video For Download...