Usage

We recommend using VS Code, which we configured to work with this project using vs.code-workspace and settings.json. You can always use a different IDE but you need to make sure to activate the virtual environment you created inside .venv folder previously.

source .venv/bin/activate

Documentation

Adding documentation is as simple as modifying mkdocs.yml and docs folder. They are self-explanatory but for a very quick guide, refer to this tutorial on how to use mkdocs. We also used GitHub Project Pages (as opposed to GitHub Organization and User Pages) as demonstrated in this tutorial. Finally, we setup a custom subdomain for the project page (consult this manual). Assuming you have already purchased a domain name and hosted your personal website on GitHub with the following records in the domain's DNS table:

Type	Name	Value
A	@	185.199.108.153
A	@	185.199.109.153
A	@	185.199.110.153
A	@	185.199.111.153
CNAME	www	<github-username>.github.io

Note: these IP addresses are from this page.

Now to link your project page to your domain as python-package.example.com add:

Type	Name	Value
CNAME	python-package	<github-username>.github.io

Then, modify the CNAME file in docs to reflect these changes.

Note: The name of the package must not have an underscore "_" in order to enable HTTPS for the domain name. Use "-" instead.

Once you are satisfied with your modifications to mkdocs.yml and the documentation folder and wants to test out your website:

mkdocs serve

If everything is in place, commit your changes first, then:

mkdocs gh-deploy

Command Line Interface (CLI)

We used click to implement a CLI for our example English dictionary package.

english

Usage: english [OPTIONS] COMMAND [ARGS]...

  English dictionary.

Options:
  -r, --run / -d, --debug  Whether to run without debugging.  [default: True]
  -v, --version            Show the version and exit.
  --help                   Show this message and exit.

Commands:
  antonyms     Get the different antonyms of a given word.
  meanings     Get the different meanings of a given word.
  suggestions  Get the different suggestions of a given word.
  synonyms     Get the different synonyms of a given word.

Linting and testing

Fortunately linting is automatically done through the recommended VS Code extensions in extensions.json. As for unit testing and code coverage, both can be achieved through pytest and pytest-cov, respectively. In theory, we could use unittest and pytest-mock to test each and every unit in our package. However, we only implemented two unit tests using click.testing. This tutorial is a good reference to get you up and running with python testing.

pytest tests  # run pytest only
py.test --cov=python_package tests  # run pytest and coverage

To incorporate this workflow with continuous integration (CI) service like Travis-CI, we can follow their documentation to generate the .travis.yml file. The final step is to link it with GitHub and maybe hook GitHup Pages deployment.