Improve documentation

Author: dolfinus

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.3.0
+  rev: v4.4.0
   hooks:
   - id: check-ast
   - id: check-case-conflict
@@ -20,7 +20,7 @@ repos:
   - id: trailing-whitespace
   - id: detect-private-key
 - repo: https://github.com/Lucas-C/pre-commit-hooks
-  rev: v1.3.1
+  rev: v1.4.2
   hooks:
   - id: remove-tabs
 - repo: https://github.com/codespell-project/codespell
@@ -29,42 +29,42 @@ repos:
   - id: codespell
     args: [-w]
 - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
-  rev: v2.4.0
+  rev: v2.7.0
   hooks:
   - id: pretty-format-yaml
     args: [--autofix, --indent, '2']
 - repo: https://github.com/pycqa/isort
-  rev: 5.10.1
+  rev: 5.12.0
   hooks:
   - id: isort
     files: setuptools_git_versioning.py
 - repo: https://github.com/pre-commit/pygrep-hooks
-  rev: v1.9.0
+  rev: v1.10.0
   hooks:
   - id: python-no-log-warn
   - id: python-no-eval
   - id: text-unicode-replacement-char
 - repo: https://github.com/asottile/pyupgrade
-  rev: v3.2.2
+  rev: v3.3.1
   hooks:
   - id: pyupgrade
     args: [--py37-plus]
 - repo: https://github.com/psf/black
-  rev: 22.10.0
+  rev: 23.1.0
   hooks:
   - id: black
     language_version: python3
 - repo: https://github.com/asottile/blacken-docs
-  rev: v1.12.1
+  rev: 1.13.0
   hooks:
   - id: blacken-docs
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v0.990
+  rev: v1.0.1
   hooks:
   - id: mypy
     additional_dependencies: [types-six, types-toml]
 - repo: https://github.com/pycqa/flake8
-  rev: 5.0.4
+  rev: 6.0.0
   hooks:
   - id: flake8
 - repo: https://github.com/PyCQA/bandit

CHANGELOG.rst

@@ -4,6 +4,21 @@ Changelog
 1.13
 ----
 
+.. changelog::
+    :version: 1.13.2
+
+    .. change::
+        :tags: docs, feature
+        :tickets: 77, 77
+
+        Recommend users to use file-based schema instead of tag-based due some cases.
+
+    .. change::
+        :tags: docs, feature
+        :tickets: 17
+
+        Add small example of ``.gitignore`` file to common issues section
+
 .. changelog::
     :version: 1.13.1
     :released: 13.11.2022

docs/common_issues/all_dirty.rst

@@ -13,3 +13,10 @@ as ``dirty``.
 
 You should such files to the ``.gitignore`` file. See `current repo .gitignore <https://github.com/dolfinus/setuptools-git-versioning/blob/master/.gitignore>`__
 as an example.
+
+In most the cases adding these lines solves the issue:
+
+.. code:: gitignore
+
+    eggs/
+    *.egg*

docs/conf.py

@@ -17,7 +17,6 @@
 from packaging.version import Version
 
 try:
-
     from setuptools_git_versioning import version_from_git
 
     ver = Version(version_from_git())
@@ -80,7 +79,11 @@
 # html_static_path = ['_static']
 
 
-extlinks = {"github-user": ("https://github.com/%s", "@%s")}
+extlinks = {
+    "github-user": ("https://github.com/%s", "@%s"),
+    "issue": ("https://github.com/dolfinus/setuptools-git-versioning/issues/%s", "#%s"),
+    "pr": ("https://github.com/dolfinus/setuptools-git-versioning/pull/%s", "#%s"),
+}
 
 changelog_sections = [
     "general",
@@ -96,7 +99,7 @@
 changelog_caption_class = ""
 
 changelog_inner_tag_sort = ["breaking", "deprecated", "feature", "bug", "refactor"]
-changelog_hive_secgions_from_tags = True
+changelog_hide_sections_from_tags = True
 
 changelog_render_ticket = "https://github.com/dolfinus/setuptools-git-versioning/issues/%s"
 changelog_render_pullreq = {"default": "https://github.com/dolfinus/setuptools-git-versioning/pull/%s"}

docs/schemas/callback/index.rst

@@ -1,7 +1,7 @@
 .. _callback-based-release:
 
-Callback-based release
-~~~~~~~~~~~~~~~~~~~~~~~
+Callback-based release (advanced)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. toctree::
     :maxdepth: 1

docs/schemas/file/index.rst

@@ -1,7 +1,14 @@
 .. _file-based-release:
 
-File-based release
-~~~~~~~~~~~~~~~~~~~~~~~
+File-based release (recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+    Prefer this schema because it allows to get a version number in the following cases:
+        * Downloading source tarball without ``.git`` folder (:issue:`77`).
+        * Shallow repo clone without tags (:issue:`75`).
+        * Getting version number from a branch which does not contain any tags (`Git-flow <https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow>`__ and its derivatives)
 
 .. toctree::
     :maxdepth: 1

docs/schemas/file/version_file.rst

@@ -1,7 +1,7 @@
 .. _version-file:
 
 Read some file content as current version
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For example, current repo state is:
 

docs/schemas/tag/index.rst

@@ -1,7 +1,11 @@
 .. _tag-based-release:
 
-Tag-based release
-~~~~~~~~~~~~~~~~~
+Tag-based release (not recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+    This schema has several drawbacks. Use :ref:`file-based schema <file-based-release>` instead.
 
 .. toctree::
     :maxdepth: 1

docs/schemas/tag/tag_release.rst

@@ -1,7 +1,7 @@
 .. _tag-release:
 
 Release is a git tag
-^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^
 
 For example, current repo state is: