[DOCS] Reference the 'biskotaki' pypi package as a generated example from this Template

Author: boromir674

README.rst

@@ -7,12 +7,10 @@ Python Package (pypi) Cookiecutter, with emphasis on CI/CD and automation.
 
 | |build| |release_version| |wheel| |supported_versions| |commits_since_specific_tag_on_master| |commits_since_latest_github_release|
 
-
 |
 | **Source Code:** https://github.com/boromir674/cookiecutter-python-package
 | **Pypi Package:** https://pypi.org/project/cookiecutter-python/
-|
-
+| **CI Pipeline:** https://github.com/boromir674/cookiecutter-python-package/actions/
 
 .. Test Workflow Status on Github Actions for specific branch <branch>
 
@@ -34,9 +32,9 @@ Python Package (pypi) Cookiecutter, with emphasis on CI/CD and automation.
     :alt: Supported Python versions
     :target: https://pypi.org/project/cookiecutter_python
 
-.. |commits_since_specific_tag_on_master| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/v0.6.1/master?color=blue&logo=github
+.. |commits_since_specific_tag_on_master| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/v0.7.2/master?color=blue&logo=github
     :alt: GitHub commits since tagged version (branch)
-    :target: https://github.com/boromir674/cookiecutter-python-package/compare/v0.6.1..master
+    :target: https://github.com/boromir674/cookiecutter-python-package/compare/v0.7.2..master
 
 .. |commits_since_latest_github_release| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/latest?color=blue&logo=semver&sort=semver
     :alt: GitHub commits since latest release (by SemVer)
@@ -55,63 +53,131 @@ Python Package (pypi) Cookiecutter, with emphasis on CI/CD and automation.
     :target: https://scrutinizer-ci.com/g/boromir674/cookiecutter-python-package/?branch=master
 
 
-
-
 Features
 ========
 
-- Python Package Project generation
-- CI pipeline to test against multiple Python versions and Platforms
-- One-line commands for DevOps activities such as 'package', 'build', 'deploy'
-- Test Suite, using Pytest
+1. Fresh **Python Package Project Generation**, "packaged" with a **Test Suite** and a **CI** Pipeline (see `Quickstart`_)
+2. **Python Package Template** (source code at `src/cookiecutter_python/`_) implemented as a `Cookiecutter`
+3. **Tested** on python versions **3.6, 2.7, 3.8, 3.9 and 3.10**, for both **"Linux"** and **"MacOS"** platforms (see `Test Workflow` on `CI`_)
+
+See the **Biskotaki** *Python Package Project*, which was entirely generated using this **Python Package Template:**
+
+* **Source Code** hosted on *Github* at https://github.com/boromir674/biskotaki
+* **Python Package** hosted on *pypi.org* at https://pypi.org/project/biskotaki/
+* **CI Pipeline** hosted on *Github Actions* at https://github.com/boromir674/biskotaki/actions
+
+Generated Python Package Features
+---------------------------------
+
+1. **Test Suite** using `pytest`_
+2. **Parallel Execution** of Unit Tests, on multiple cpu's
+3. **Automation**, using `tox`_
+
+   a. **Code Coverage** measuring
+   b. **Build Command**, using the `build`_ python package
+   c. **Pypi Deploy Command**, supporting upload to both `pypi.org`_ and `test.pypi.org`_ servers
+   d. **Type Check Command**, using `mypy`_
+4. **CI Pipeline**, running on `Github Actions`_
+
+   a. **Job Matrix**, spanning different `platform`'s and `python version`'s
+
+      1. Platfroms: `ubuntu-latest`, `macos-latest`
+      2. Python Interpreters: `3.6`, `3.7`, `3.8`, `3.9`, `3.10`
+   b. **Parallel Job** execution, generated from the `matrix`, that runs the `Test Suite`
+
 
+Quickstart
+==========
 
 Prerequisites
-=============
+-------------
 
 You need to have Cookiecutter installed.
 Check the `Cookiecutter documentation`_ pages for more on Cookiecutter.
 
 
 Usage
-=====
-
-Simply, get (clone) the code and generate a Project based on the (downloaded) template.
+-----
 
 Open a console/terminal and run:
 
-.. code-block:: sh
+  .. code-block:: sh
 
-    git clone git@github.com:boromir674/cookiecutter-python-package.git
+      git clone git@github.com:boromir674/cookiecutter-python-package.git
+      cookiecutter cookiecutter-python-package/src/cookiecutter_python
 
-    cookiecutter cookiecutter-python-package/src/cookiecutter_python
+Now, you should have generated a new Project for a Python Package, based on the `Template`_!
 
+    Just 'enter' (`cd` into) the newly created directory, ie `cd <my-great-python-package>`.
 
-This will generate a new `Python Package Project` (in the currect dir), using the template from github.
-It shall prompt you to enter the necessary initial information to generate the project in a typical cookiecutter fashion.
+Develop your package's **Source Code** (`business logic`) inside `src/my_great_python_package` dir :)
 
+Develop your package's **Test Suite** (ie `unit-tests`, `integration tests`) inside `tests` dir :)
 
-Modifying the Template
-======================
 
-You can always adjust the template to your needs, before generating a new Project.
+Try yourself!
+^^^^^^^^^^^^^
 
-Open a console/terminal and run:
+You are ready to enjoy some of the package's **features** available out-of-the-box!
+
+For instance:
+
+1. Leverage the supplied `tox environments` to automate various **Testing** and **DevOps** related activities.
+
+   Assuming you have `tox` installed (example installation command: `python3 -m pip install --user tox`)
+   and you have done a `cd` into the newly generated Project directory, you can do for example:
+
+   a. Run the **Test Suite** against different combinations of `Python versions` (ie 3.7, 3.8) and different ways of installing (ie 'dev', 'sdist', 'wheel') the `<my_great_python_package>` package:
+
+      .. code-block:: sh
+
+         tox -e "py{3.7, 3.8}-{dev, sdist, wheel}"
+
+   b. Check the code for **compliance** with **best practises** of the `Python packaging ecosystem` (ie PyPI, pip),
+      build `sdist` and `wheel` distributions and store them in the `dist` directory:
+
+      .. code-block:: sh
+
+           tox -e check && tox -e build
+
+   c. **Deploy** the package's distributions in a `pypi` (index) server:
 
-.. code-block:: bash
+      1. Deploy to **staging**, using the `test` pypi (index) server at `test.pypi.org`_:
 
-    git clone git@github.com:boromir674/cookiecutter-python-package.git
-    cd cookiecutter-python-package
+         .. code-block:: sh
 
+             TWINE_USERNAME=username TWINE_PASSWORD=password PACKAGE_DIST_VERSION=1.0.0 tox -e deploy
 
-Now, you should be inside the `cookiecutter-python-package` repository (directory)
-and the actual Template, that you can modify, is inside the `src/cookiecutter_python` sub directory.
+      2. Deploy to **production**, using the `production` pypi (index) server at `pypi.org`_:
 
-After, finishing the modifications you can run something like:
+         .. code-block:: sh
 
-.. code-block:: bash
+             TWINE_USERNAME=username TWINE_PASSWORD=password PACKAGE_DIST_VERSION=1.0.0 PYPI_SERVER=pypi tox -e deploy
 
-    cookiecutter src/cookiecutter_python --output-dir <your-new-project-dir>
+         .. note::
+            Setting PYPI_SERVER=pypi indicates to deploy to `pypi.org` (instead of `test.pypi.org`).
+
+      .. note::
+         Please modify the TWINE_USERNAME, TWINE_PASSWORD and PACKAGE_DIST_VERSION envronment variables, accordingly.
+
+         TWINE_USERNAME & TWINE_PASSWORD are used to authenticate (user credentials) with the targeted pypi server.
+
+         PACKAGE_DIST_VERSION is used to avoid accidentally uploading distributions of different versions than intented.
+
+
+2. Leverage the **CI Pipeline** and its **build matrix** to run the **Test Suite** against a combination of
+   different Platforms, different Python interpreter versions and different ways of installing the subject Python Package:
+
+    `Trigger` the **Test Workflow** on the **CI server**, by `pushing` a git commit to a remote branch (ie `master` on github).
+
+    `Navigate` to the `CI Pipeline web interface` (hosted on `Github Actions`) and inspect the **build** results!
+
+
+   .. note::
+      You might have already `pushed`, in case you answered `yes`, in the `initialize_git_repo` prompt, while generating the Python Package,
+      and in that case, the **Test Workflow** should have already started running!
+
+      Out-of-the-box, `triggering` the **Test Workflow** happens only when pushing to the `master` or `dev` branch.
 
 
 License
@@ -120,7 +186,39 @@ License
 * Free software: Affero GNU General Public License v3.0
 
 
+Notes
+=====
+
+Currently, since the actual `cookiecutter` template does not reside on the `root` directory
+of the repository (but rather in `src/cookiecutter_python`), 'cloning' the repository
+locally is required at first.
+
+This was demonstrated in the `quickstart` section, as well.
+
+For more complex use cases, you can modify the Template and also leverage all of
+`cookiecutter`'s features, according to your needs.
+
 
 .. URL LINKS
 
 .. _Cookiecutter documentation: https://cookiecutter.readthedocs.io/en/stable/
+
+.. _CI: https://github.com/boromir674/cookiecutter-python-package/actions
+
+.. _tox: https://tox.wiki/en/latest/
+
+.. _pytest: https://docs.pytest.org/en/7.1.x/
+
+.. _build: https://github.com/pypa/build
+
+.. _pypi.org: https://pypi.org/
+
+.. _test.pypi.org: https://test.pypi.org/
+
+.. _mypy: https://mypy.readthedocs.io/en/stable/
+
+.. _Github Actions: https://github.com/boromir674/cookiecutter-python-package/actions
+
+.. _src/cookiecutter_python/: https://github.com/boromir674/cookiecutter-python-package/tree/master/src/cookiecutter_python
+
+.. _Template: https://github.com/boromir674/cookiecutter-python-package/tree/master/src/cookiecutter_python

setup.cfg

@@ -1,7 +1,7 @@
 [metadata]
 ## Setuptools specific information
 name = cookiecutter_python
-version = 0.6.1
+version = 0.7.2
 # renders on pypi as subtitle
 description = Yet another modern Python Package (pypi) with emphasis in CI/CD and automation 
 long_description = file: README.rst
@@ -15,16 +15,19 @@ author_email = k.lampridis@hotmail.com
 # represents the web home page of the project
 url = https://github.com/boromir674/cookiecutter-python-package
 
-download_url = https://github.com/boromir674/cookiecutter-python-package/archive/v0.6.1.tar.gz
+download_url = https://github.com/boromir674/cookiecutter-python-package/archive/v0.7.2.tar.gz
 
 ## PyPi specific information
 project_urls =
-    Documentation = https://cookiecutter-python-package.readthedocs.io/
     Bug Tracker = https://github.com//cookiecutter-python-package/issues
+    CI: Github Actions = https://github.com/boromir674/cookiecutter-python-package/actions
+    Documentation = https://cookiecutter-python-package.readthedocs.io/
     Source Code = https://github.com/boromir674/cookiecutter-python-package
     ; Changelog = https://cookiecutter-python-package.readthedocs.io/en/stable/changelog.html
+    ; Code of Conduct = TODO
+    ; Mailing lists =
 
-keywords = python library
+keywords = python package template, python package generator, cookiecutter, python package
 classifiers =
     Development Status :: 5 - Production/Stable
     Intended Audience :: Developers

src/cookiecutter_python/__init__.py

@@ -1 +1 @@
-__version__ = '0.6.1'
+__version__ = '0.7.2'

src/cookiecutter_python/{{ cookiecutter.project_slug }}/README.rst

@@ -44,16 +44,36 @@
 Features
 ========
 
-- TODO-feature 1
-- TODO-feature 2
+
+1. **{{ cookiecutter.pkg_name }}** `python package`
+
+   a. **Great Feature**
+   b. **Nice Feature**
+
+2. **Test Suite** using `Pytest`
+3. **Parallel Execution** of Unit Tests, on multiple cpu's
+4. **Automation**, using `tox`
+
+   a. **Code Coverage** measuring
+   b. **Build Command**, using the `build` python package
+   c. **Pypi Deploy Command**, supporting upload to both `pypi.org` and `test.pypi.org` servers
+   d. **Type Check Command**, using `mypy`
+5. **CI Pipeline**, running on `Github Actions`
+
+   a. **Job Matrix**, spanning different `platform`'s and `python version`'s
+
+      1. Platfroms: `ubuntu-latest`, `macos-latest`
+      2. Python Iterpreters: `3.6`, `3.7`, `3.8`, `3.9`, `3.10`
+   b. **Parallel Job** execution, generated from the `matrix`, that runs the `Test Suite`
+
 
 Prerequisites
 =============
 
-You need to have Python installed.
+You need to have `Python` installed.
 
-Installation
-============
+Quickstart
+==========
 
 Using `pip` is the approved way for installing `{{ cookiecutter.pkg_name }}`.
 
@@ -62,10 +82,7 @@ Using `pip` is the approved way for installing `{{ cookiecutter.pkg_name }}`.
     python3 -m pip install {{ cookiecutter.pkg_name }}
 
 
-Usage
-=====
-
-TODO
+TODO demonstrate a use case
 
 License
 =======

src/cookiecutter_python/{{ cookiecutter.project_slug }}/setup.cfg

@@ -17,14 +17,19 @@ url = https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.repo
 
 download_url = https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.repo_name }}/archive/v{{ cookiecutter.version }}.tar.gz
 
+
 ## PyPi specific information
 project_urls =
+    Bug Tracker = https://github.com/{{ cookiecutter.repo_name }}/issues
+    CI: Github Actions = https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.repo_name }}/actions
     Documentation = https://{{ cookiecutter.repo_name }}.readthedocs.io/
-    Bug Tracker = https://github.com//{{ cookiecutter.repo_name }}/issues
     Source Code = https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.repo_name }}
     ; Changelog = https://{{ cookiecutter.repo_name }}.readthedocs.io/en/stable/changelog.html
+    ; Code of Conduct = TODO
+    ; Mailing lists =
+
 
-keywords = python library
+keywords = python package,
 classifiers =
     Development Status :: 5 - Production/Stable
     Intended Audience :: Developers