Add example docs (#1)

* Add example docs

* Fix up the toc

* Add installation docs page.

* Add getting started docs

* Add contributing documentation

* Update the readme for the example repo

Author: tim-schilling

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)

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)

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 [email protected]:[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/*
+```

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())
+```

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
+```