1. Including licences and writing READMEs
Your package is really coming along! However, there are a couple of really important pieces missing - the license and a README file.
2. Why do I need a license?
The license is a really important file for code you want to share online. If you host your package online, but do not include a license, then you are not giving permission to other people to share, modify or even use the code!
Many great packages are open source and may be freely modified and shared by other users. This openness has led to the success of many of these packages as they have attracted developers to work on them.
3. Open source licenses
There are lots of different licenses you might include, and we can't go into all of these in this course.
If you would like to open source your package, then I thoroughly recommend you to find out information about these license choices here.
All of the open source licenses on this popular website allow individuals to use your package themselves, and to modify and share it. Some licenses might require modified versions of the package to be open sourced, and shared with the same license you used.
4. What is a README?
Another important file for your project is your README. This file acts as the front page of your package. If you host your package online on Github or PyPI then your README will be displayed there.
5. What to include in a README
What you include is mostly up to you, but a good README will have the package title; a description of the package including its most important features; instructions on how to install the package; some example uses to get started; a section on how to contribute to the package code; and a brief note on the type of license used.
6. README format
Just like there are multiple formats for documentation, there are two formats used for READMEs - reStructuredText and markdown.
In this course, you'll use markdown to write your README. It is slightly simpler than reStructuredText and is a common choice in the wild. Most of what you write in markdown will be easy to convert to reStructuredText if you ever need a more complex README.
7. Commonmark
There are some slightly different versions of markdown out there. But the version for READMEs is called commonmark.
Commonmark is a file format like HTML, but is much much simpler. On the left you can see what is inside the README markdown file, and the on the right is what gets displayed when the file is rendered.
8. Commonmark
You can add titles using a hashtag; you can add text, and make a section bold by wrapping it in double asterisks; you can add links like this;
9. Commonmark
you can add subtitles using multiple hashtags;
10. Commonmark
and even add code samples by wrapping it in triple backticks.
11. Adding these files to your package
The license and README files should be added to the top directory, alongside the setup script and the requirements file.
12. MANIFEST.in
There is one last file you will need to create before you can release your package to the world. This is the manifest-dot-in file. This file is used to list all of the extra files that you want to distribute along with your package. You'll learn more about distributing you package in the next lesson.
This manifest file is important because by default your license will not be included when someone downloads your package, and neither will your README.
13. MANIFEST.in
Inside the manifest file we just need to include the license and the README like this.
14. Let's practice!
Okay, now it's time to go and add the last few files you need to make your package publishable. Let's practice!