From 3b6514dd7d000b11d198e63e5ab957306fc2984e Mon Sep 17 00:00:00 2001 From: konstantinos Date: Tue, 17 May 2022 18:21:55 +0300 Subject: [PATCH 1/4] docs(cli): document installation and cli usage --- README.rst | 9 +++- docs/contents/30_usage/generate_project.rst | 22 ++++++-- docs/contents/30_usage/index.rst | 12 +++-- docs/contents/30_usage/installation.rst | 57 ++++++++++++++++----- 4 files changed, 77 insertions(+), 23 deletions(-) diff --git a/README.rst b/README.rst index c3b48793..ce9c43ad 100755 --- a/README.rst +++ b/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| | @@ -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 diff --git a/docs/contents/30_usage/generate_project.rst b/docs/contents/30_usage/generate_project.rst index 9bd194e5..8a0eb1ce 100644 --- a/docs/contents/30_usage/generate_project.rst +++ b/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. diff --git a/docs/contents/30_usage/index.rst b/docs/contents/30_usage/index.rst index 9dbb2d6d..f7da11a2 100644 --- a/docs/contents/30_usage/index.rst +++ b/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 diff --git a/docs/contents/30_usage/installation.rst b/docs/contents/30_usage/installation.rst index 9fae3238..19acca88 100644 --- a/docs/contents/30_usage/installation.rst +++ b/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 From b323d22b1f2c8409a3b4e80657bfe89db4011457 Mon Sep 17 00:00:00 2001 From: konstantinos Date: Tue, 17 May 2022 18:23:36 +0300 Subject: [PATCH 2/4] release(semantic_version): bump version to 1.1.1 --- README.rst | 4 ++-- setup.cfg | 4 ++-- src/cookiecutter_python/__init__.py | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index ce9c43ad..427546e3 100755 --- a/README.rst +++ b/README.rst @@ -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) diff --git a/setup.cfg b/setup.cfg index 9af97dfc..73d54d3d 100755 --- a/setup.cfg +++ b/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 = 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/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 = diff --git a/src/cookiecutter_python/__init__.py b/src/cookiecutter_python/__init__.py index 1a72d32e..b3ddbc41 100755 --- a/src/cookiecutter_python/__init__.py +++ b/src/cookiecutter_python/__init__.py @@ -1 +1 @@ -__version__ = '1.1.0' +__version__ = '1.1.1' From 36afb9cd6f69a2d606cf70fe3ecfed31bd1c2b10 Mon Sep 17 00:00:00 2001 From: konstantinos Date: Tue, 17 May 2022 18:23:37 +0300 Subject: [PATCH 3/4] docs: update changelog with the release's changes --- CHANGELOG.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index f263ce60..4f9a3429 100755 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -2,6 +2,14 @@ Changelog ========= +1.1.1 (2022-05-17) +------------------ + +documentation +^^^^^^^^^^^^^ +- document installation and cli usage + + 1.1.0 (2022-05-17) ================== From 806bb5a89c058987acc1518902f04b0f30e35c33 Mon Sep 17 00:00:00 2001 From: konstantinos Date: Tue, 17 May 2022 18:25:12 +0300 Subject: [PATCH 4/4] docs(changelog): match previous entries format style --- CHANGELOG.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 4f9a3429..2ae8a4de 100755 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -3,10 +3,13 @@ Changelog ========= 1.1.1 (2022-05-17) ------------------- +================== + +Changes +^^^^^^^ documentation -^^^^^^^^^^^^^ +""""""""""""" - document installation and cli usage