[DOCS] Installation guide & cli Usage

CHANGELOG.rst

@@ -2,6 +2,17 @@
 Changelog
 =========
 
+1.1.1 (2022-05-17)
+==================
+
+Changes
+^^^^^^^
+
+documentation
+"""""""""""""
+- document installation and cli usage
+
+
 1.1.0 (2022-05-17)
 ==================
 

README.rst

@@ -5,7 +5,7 @@ Python Package (pypi) Cookiecutter, with emphasis on CI/CD and automation.
 
 .. start-badges
 
-| |build| |docs| |coverage| |ossf| |maintainability| |better_code_hub| |codacy| |tech-debt|
+| |build| |docs| |coverage| |ossf| |maintainability| |better_code_hub| |codacy| |tech-debt| |black|
 | |release_version| |wheel| |supported_versions| |gh-lic| |commits_since_specific_tag_on_master| |commits_since_latest_github_release|
 
 |
@@ -196,9 +196,9 @@ For more complex use cases, you can modify the Template and also leverage all of
 
 .. Github Releases & Tags
 
-.. |commits_since_specific_tag_on_master| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/v1.1.0/master?color=blue&logo=github
+.. |commits_since_specific_tag_on_master| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/v1.1.1/master?color=blue&logo=github
     :alt: GitHub commits since tagged version (branch)
-    :target: https://github.com/boromir674/cookiecutter-python-package/compare/v1.1.0..master
+    :target: https://github.com/boromir674/cookiecutter-python-package/compare/v1.1.1..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)
@@ -248,3 +248,10 @@ For more complex use cases, you can modify the Template and also leverage all of
 .. |tech-debt| image:: https://img.shields.io/codeclimate/tech-debt/boromir674/cookiecutter-python-package
     :alt: Code Climate technical debt
     :target: https://codeclimate.com/github/boromir674/cookiecutter-python-package/
+
+
+.. Code Style with Black
+
+.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :alt: Black
+    :target: https://github.com/psf/black

docs/contents/30_usage/generate_project.rst

@@ -1,10 +1,22 @@
 
-| The most common way to generate a new Python Package Project (in the current working directory),
-| is to invoke the *generate-python* cli (while supplying the necessary initial
-| information if/when prompted).
+| Using the cli is as simple as invoking `generate-python` from a console.
 
-Open a console (ie terminal) and run: 
+You can run the following to see all the available parameters you can control:
 
 .. code-block:: shell
-  
+
+  generate-python --help
+
+The most common way to generate a new Python Package Project is to run:
+
+.. code-block:: shell
+
   generate-python
+
+This will prompt you to input some values and create a fresh new Project in the
+current directory!
+
+Now, simply `cd` into the generated Project's directory and enjoy some
+of the features the generator supplies new projects with!
+
+More on use cases in the next section.

docs/contents/30_usage/index.rst

@@ -2,15 +2,19 @@
 Generate New Python Package Project
 ===================================
 
-This *pyton generator* was designed to be installed via *pip* and then invoked through
+This *python generator* was designed to be installed via *pip* and then invoked through
 the cli.
 
-------------
-Installation
-------------
+------------------
+Installing the cli
+------------------
 
 .. include:: installation.rst
 
+-------------
+Using the cli
+-------------
+
 .. include:: generate_project.rst
 
 

docs/contents/30_usage/installation.rst

@@ -6,46 +6,77 @@
 Install as PyPi package
 -----------------------
 
+Installing `cookiecutter-python` with `pip` is the way to go, for getting the
+`generate-python` cli onto your machine. Here we demonstrate how to do that using a
+
 
 In virtual environment (recommended)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The recommended way of installing any python package, is use a *python virtual environment*.
+As with any Python Package, it is recommended to install *cookiecutter-python* inside a
+python *virtual environment*. You can use any of `virtualenv`, `venv`, `pyenv` of the
+tool of your choice. Here we demonstrate, using `virtualenv`, by running the following commands
+in a console (aka terminal):
+
+1. Create a virtual environment
+
+  .. code-block:: shell
+
+    virtualenv env --python=python3
 
 Open a console (aka terminal) and run:
 
-.. code-block:: shell
+2. Activate environment
+
+  .. code-block:: shell
+
+    source env/bin/activate
+
+3. Install `cookiecutter-python`
+
+  .. code-block:: shell
 
-  virtualenv env --python=python3
-  source env/bin/activate
+    pip install cookiecutter-python
 
-  pip install cookiecutter-python
+4. Create symbolic link for the (current) user
 
-  deactivate
+  .. code-block:: shell
+
+    ln -s env/bin/generate-python ~/.local/bin/generate-python
 
-  ln -s env/bin/generate-python ~/.local/bin/generate-python
 
 Now the *generate-python* executable should be available (assuming ~/.local/bin is in your PATH)!
 
 
-For user 
-^^^^^^^^
+For user (option 2)
+^^^^^^^^^^^^^^^^^^^
 
 One could also opt for a *user* installation of *cookiecutter-python* package:
 
-.. code-bloack: shell
+.. code-block:: shell
 
   python3 -m pip install --user cookiecutter-python
 
 
-For all users
-^^^^^^^^^^^^^
+For all users (option 3)
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 The least recommended way of installing *cookiecutter-python* package is to
 *directly* install in the *host* machine:
 
-.. code-bloack: shell
+.. code-block:: shell
 
   sudo python3 -m pip install cookiecutter-python
 
 Note the need to invoke using *sudo*, hence not that much recommended.
+
+
+Check installation
+------------------
+
+| Now the `generate-python` cli should be available!
+| You can verify by running the following:
+
+.. code-block:: shell
+
+  generate-python --version

setup.cfg

@@ -1,7 +1,7 @@
 [metadata]
 ## Setuptools specific information
 name = cookiecutter_python
-version = 1.1.0
+version = 1.1.1
 # 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,7 +15,7 @@ author_email = [email protected]
 # 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/v1.1.0.tar.gz
+download_url = https://github.com/boromir674/cookiecutter-python-package/archive/v1.1.1.tar.gz
 
 ## PyPi specific information
 project_urls =

src/cookiecutter_python/__init__.py

@@ -1 +1 @@
-__version__ = '1.1.0'
+__version__ = '1.1.1'