package_name

A generic python PyPi project template. Replace this line with a project description

---

**This file is meant to be a template but my recommendation is to fork it and make it your own for what suits your projects. After completing the TODO section take a look at the end of the file for final touches.

Video guide for usage of the package template can be found here.**

TODO

• Setup a github project board. Here are a few examples of some boards; sdu, pystall, ahd
• Replace all instances of package_name in this file
• Finish creating setup.py
• Update mkdocs.yml or remove it if you don't intend to have user docs. Take a look at ahd for a great example of setting up the docs folder and configuring mkdocs.yml
• Fill out features & Roadmap section
• Fill out quick start
• Create the actual package code
• Fill out or remove the following sections
  • What does package_name do?
  • Examples
  • Why should I use package_name?
  • Who is package_name for?
  • Arguments
  • Additional documentation
• Remove From PyPi section if you don't intend to publish it to PyPi
• Remove any outstanding sections from Table of Contents
• Fill out CONTRIBUTING.md
• Fill out CHANGELOG.md
• Create tests, see creating tests if you have never made tests before
• Do (or don't) final touches, then remove this whole section from your readme

Final Touches

These are all optional extras you can do to make your project better, you can either do them or just delete this whole section.

Uploading to PyPi

Now that you have finished the todo section (and assuming you want people to be able to pip install without downloading the source) it can be published on PyPi by first signing up for an account, then running nox -s release. The release session will build a distribution, prompt you to make sure you have filled out all the information necessary and then start the upload to PyPi (you will then have to login to PyPi through the command line).

ReadTheDocs

There are some optional extras, for example if you signup for a readthedocs account you can host your documentation with a single click. Alternatively if you want to use a custom theme for your documentation you can use github pages and run mkdocs gh-deploy which will do the documentation building for you. From there you can follow this guide to setup your github pages for your project, by default running mkdocs gh-deploy will create a gh-pages branch for you so you can just hit that checkbox in the repositories settings to get setup.

Auto generated API docs

If you have written an API and want to use API documentation that autobuilds based on docstrings like sdu, I would highly recommend pdoc3. This package will allow you to build the docs very easily, check out their documentation for details.

Creating tests

If you have never created tests before, take a look at the pytest docs and this video or this video.

Setting up deepsource.io

Deepsource.io is an incrediby useful tool I have found that will scan your github repo and warn you about potential security issues, anti-patterns, and style guide infractions you've made. It is completely free for pulic repo's and has saved me a few times from some prety big mistakes.

---

Table of Contents

• What does package_name do?
• Features & Roadmap
• Why should I use package_name?
• Who is package_name for?
• Quick-start
  • Installation
    • From source
    • From PyPi
    • Examples
• Usage
  • Arguments
• Additional Documentation

What does package_name do?

Provide a brief exposition on what the purpose of your package is, or change this heading to goals (like sdu)

Features & Roadmap

Include a bullet point list of implemented features, and either a link to the github planning board or list of coming-soon features

Why should I use package_name?

If there are well-known alternatives provide details about why people should use your package instead

Who is package_name for?

If your package has multiple uses in seperate domains it may be worth explaning use cases in different domains; see ahd for example

Quick-start

Include how people can get started using your project in the shortest time possible

Installation

From source

1. Clone this repo: (put github/source code link here)
2. Run pip install . or sudo pip3 install .in the root directory

From PyPi

1. Run pip install package_name

Examples

Include an example or two of usage, or common use cases

Usage

Include how to use your package as an API (if that's what you're going for)

Arguments

If you are writing a script, include some helpful/often used arguments here. If you decide to use docopt the usage string should do.

Additional Documentation

If you have any supplementary documentation elsewhere (i.e. https://readthedocs.org/) include references to it here.