diff --git a/README.md b/README.md index b95dce7..7277628 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,6 @@ -# django-commons-playground -A sample project to test things out +# Django Commons example repository +This is an example repository for Django Commons. Some relevant areas to review are: -## Running tests - -```shell -python -m unittest -``` - -## Manually building and uploading - -```shell -python3 -m pip install -U twine build -python3 -m build -python3 -m twine upload --repository testpypi dist/* -``` +- GitHub action ([release.yml](https://github.com/django-commons/django-commons-playground/blob/main/.github/workflows/release.yml)) for releasing to PyPI +- [Documentation](docs/README.md) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..6cd2e7c --- /dev/null +++ b/docs/README.md @@ -0,0 +1,13 @@ +# Documentation + +The documentation for Django Commons Playground serves as an example for what +a repository should contain. The structure doesn't have to be exactly the same +as this, but it's a starting point. Any docs is better than no docs. Maintained +and organized docs are the best docs. + +## Table of Contents + +- [Installation](installation.md) +- [Getting Started](getting_started.md) +- [Contributing](contributing.md) +- [Code of Conduct](../CODE_OF_CONDUCT.md) diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..ac3b55e --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,50 @@ +# Contributing + +Everyone is welcome to contribute to `django-commons-playground`. We strictly +enforce our [Code of Conduct](../CODE_OF_CONDUCT.md), so please review it before +contributing. + +## Getting started + +1. [Fork the repository](https://github.com/django-commons/django-commons-playground/fork) +2. Clone your fork of the repository `git clone git@github.com:[YOUR_USERNAME_HERE]/django-commons-playground.git && cd django-commons-playground` +3. Create a venv and activate it `python -m venv venv && source venv/bin/activate` +4. Create a feature branch for your work `git checkout -b relevant-branch-name-here` +5. Implement your changes, run the tests and make a commit to your branch +6. Push your branch to GitHub `git push origin relevant-branch-name-here` +7. Create a [PR on the upstream repo (this repo)](https://github.com/django-commons/django-commons-playground/pulls) + +## Architecture + +The django-commons-playground is a collection of utility functions with a +playground theme. The purpose is to serve as an example to inbound repositories. +Because of that the documentation, pre-commit configuration and GitHub actions +are the most important aspects of the project. The code itself is secondary. + +## Running the tests + +```shell +python3 -m unittest +``` + +Nothing special here! + +## Releasing + +The repo is configured to [automatically release to PyPI](https://github.com/django-commons/django-commons-playground/blob/main/.github/workflows/release.yml) +when a new tag is pushed to GitHub. This makes use of [PyPI's trusted publishers](https://docs.pypi.org/trusted-publishers/). + +### Manual releases + +In the case a manual release is necessary, you'll need to use [Twine](https://github.com/pypa/twine) and [Build](https://github.com/pypa/build). + +```shell +# Install packaging dependencies +python3 -m pip install -U twine build +# Build the project +python3 -m build +# Release to test PyPI +python3 -m twine upload --repository testpypi dist/* +# Release to PyPI +python3 -m twine upload dist/* +``` diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000..441b209 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,12 @@ +# Getting Started + +This is an example project. You should not be using this. That said, +after [installing the project](installation.md), you can use the functionality +as such: + +```python +from django_commons_playground import playground + +print(playground.seesaw()) +print(playground.seesaw()) +``` diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..84fb372 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,16 @@ +# Installation + +This section explains how to install `django-commons-playground` to use within +your project. It assumes you have a working installation of Python 3. + +1. Create venv/virtualenv (`python -m venv venv`) +2. Activate venv/virtualenv (`source venv/bin/activate`) +3. Install `django-commons-playground` (`pip install django-commons-playground`) + +All together now: + +```shell +python -m venv venv +source venv/bin/activate +pip install django-commons-playground +```