-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* 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
- Loading branch information
1 parent
8e7f1c4
commit 58aa553
Showing
5 changed files
with
95 additions
and
15 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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/* | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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()) | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
``` |