Allow setuptools-git-versioning script to infer version from setup.py, add logging and improve docs

Author: dolfinus

.pre-commit-config.yaml

@@ -62,7 +62,7 @@ repos:
   rev: v0.961
   hooks:
   - id: mypy
-    additional_dependencies: [types-six, types-toml]
+    additional_dependencies: [types-six, types-toml, types-Deprecated]
 - repo: https://github.com/pycqa/flake8
   rev: 4.0.1
   hooks:

CHANGELOG.rst

@@ -20,7 +20,17 @@ Changelog
     .. change::
         :tags: core, feature
 
-        Add ``cwd`` argument to most of functions, allowing to get versions a specific repo folder
+        Add ``cwd`` argument to most of functions, allowing to get versions of a specific repo without changing current directory
+
+    .. change::
+        :tags: dev, feature
+
+        Add info and debug messages to the module
+
+    .. change::
+        :tags: docs, feature
+
+        Add documentation for ``setuptools-git-versioning`` script
 
 1.10
 ----

README.rst

@@ -40,7 +40,6 @@ version number according :pep:`440`.
 
 - Well-documented
 
-
 See `difference <https://setuptools-git-versioning.readthedocs.io/en/latest/differences.html>`_
 between ``setuptools-git-versioning`` and other tools.
 
@@ -86,7 +85,7 @@ and a section ``tool.setuptools-git-versioning`` with config options:
     [tool.setuptools-git-versioning]
     enabled = true
 
-And check the package version generated:
+And check the package version generated (see :ref:`command` help):
 
 .. code:: bash
 
@@ -116,7 +115,7 @@ and then add new argument ``setuptools_git_versioning`` with config options:
         setup_requires=["setuptools-git-versioning<2"],
     )
 
-And check the package version generated:
+And check the package version generated (see :ref:`command` help):
 
 .. code:: bash
 

docs/command.rst

@@ -0,0 +1,102 @@
+.. _command:
+
+Console command
+-----------------------------------
+
+Package contains script `setuptools-git-versioning` which can be used for calculating version number.\
+
+See :ref:`_installation` instruction for creating the repo with your package.
+
+To get current package version in `mypackage` repo just execute:
+
+.. code:: bash
+
+    $ cd /path/to/mypackage
+    $ setuptools-git-versioning
+    0.0.1
+
+    # or pass path to your repo explicitly
+
+    $ setuptools-git-versioning /path/to/mypackage
+    0.0.1
+
+Version will be printed to ``stdout``.
+
+This script is a wrapper for ``setuptools_git_versioning`` module, you just call it:
+
+.. code:: bash
+
+    $ python -m setuptools_git_versioning /path/to/mypackage
+    0.0.1
+
+``-v`` option enables verbose output which is useful for debugging, messages are printed to ``stderr``:
+
+.. code:: bash
+
+    $ setuptools-git-versioning /path/to/mypackage -v
+
+    INFO: No explicit config passed
+    INFO: Searching for config files in '/path/to/mypackage' folder
+    INFO: Trying 'setup.py' ...
+    INFO: '/path/to/mypackage/pyproject.toml' does not exist
+    INFO: Getting latest tag
+    INFO: Latest tag: '1.0.0'
+    INFO: Tag SHA-256: '8dc9881eacd373cb34c5d3f99a6ad9e2349a79c4'
+    INFO: Parsing tag_formatter 'util:tag_formatter' of type 'str'
+    INFO: Is dirty: False
+    INFO: HEAD SHA-256: '8dc9881eacd373cb34c5d3f99a6ad9e2349a79c4'
+    INFO: Commits count between HEAD and latest tag: 0
+    INFO: HEAD is tagged: True
+    INFO: Current branch: 'master'
+    INFO: Using template from 'template' option
+    INFO: Version number after resolving substitutions: '1.0.0'
+    INFO: Result: '1.0.0'
+
+    1.0.0
+
+
+``-vv`` shows even more debug messages:
+
+.. code:: bash
+
+    $ setuptools-git-versioning /path/to/mypackage -vvv
+
+     INFO: No explicit config passed
+     INFO: Searching for config files in '/path/to/mypackage' folder
+     INFO: Trying 'setup.py' ...
+    DEBUG: Adding '/path/to/mypackage' folder to sys.path
+     INFO: '/path/to/mypackage/pyproject.toml' does not exist
+     INFO: Getting latest tag
+    DEBUG: Sorting tags by 'creatordate'
+    DEBUG: Executing 'git tag --sort=-creatordate --merged' at '/path/to/mypackage'
+     INFO: Latest tag: '1.0.0'
+    DEBUG: Executing 'git rev-list -n 1 "1.0.0"' at '/path/to/mypackage'
+     INFO: Tag SHA-256: '8dc9881eacd373cb34c5d3f99a6ad9e2349a79c4'
+     INFO: Parsing tag_formatter 'util:tag_formatter' of type 'str'
+    DEBUG: Executing 'from mypkg.util import tag_formatter'
+    DEBUG: Tag after formatting: '1.0.0'
+    DEBUG: Executing 'git status --short' at '/path/to/mypackage'
+     INFO: Is dirty: False
+    DEBUG: Executing 'git rev-list -n 1 "HEAD"' at '/path/to/mypackage'
+     INFO: HEAD SHA-256: '8dc9881eacd373cb34c5d3f99a6ad9e2349a79c4'
+    DEBUG: Executing 'git rev-list --count HEAD "^8dc9881eacd373cb34c5d3f99a6ad9e2349a79c4"' at '/path/to/mypackage'
+     INFO: Commits count between HEAD and latest tag: 0
+     INFO: HEAD is tagged: True
+    DEBUG: Executing 'git rev-parse --abbrev-ref HEAD' at '/path/to/mypackage'
+     INFO: Current branch: 'master'
+     INFO: Using template from 'template' option
+    DEBUG: Template: '{tag}'
+    DEBUG: Args:()
+     INFO: Version number after resolving substitutions: '1.0.0'
+     INFO: Result: '1.0.0'
+
+    1.0.0
+
+
+Command help
+~~~~~~~~~~~~~
+
+.. argparse::
+    :module: setuptools_git_versioning
+    :func: _parser
+    :prog: setuptools-git-versioning

docs/conf.py

@@ -49,6 +49,7 @@
     "sphinx_autodoc_typehints",
     "changelog",
     "numpydoc",
+    "sphinxarg.ext",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/index.rst

@@ -15,6 +15,7 @@
     :hidden:
 
     install
+    command
     schemas/index
     options/index
     substitutions/index

docs/install.rst

@@ -1,3 +1,4 @@
 .. _installation:
+
 .. include:: ../README.rst
   :start-after: installation

requirements-doc.txt

@@ -2,4 +2,5 @@ changelog
 furo
 numpydoc
 sphinx
+sphinx-argparse
 sphinx-autodoc-typehints

requirements.txt

@@ -1,3 +1,4 @@
+deprecated
 packaging
 setuptools
 toml>=0.10.2

setup.py

@@ -18,7 +18,7 @@ def parse_requirements(file_content):
 
 setup(
     name="setuptools-git-versioning",
-    version=version_from_git(),
+    version=version_from_git(root=HERE),
     author="dolfinus",
     author_email="[email protected]",
     description="Use git repo data for building a version number according PEP-440",