Add Makefile for docs

dolfinus · dolfinus · commit 7d79294d703e · 2022-01-06T02:16:21.000+03:00
diff --git a/.gitignore b/.gitignore
@@ -2,11 +2,6 @@
 !.vscode/launch.json
 !.vscode/settings.json
 !.vscode/tasks.json
-# Byte-compiled / optimized / DLL files
-# Distribution / packaging
-# JetBrains
-# Python
-# VSCode
 *$py.class
 *.egg
 *.egg-info/
@@ -21,6 +16,7 @@ __pycache__/
 build/
 develop-eggs/
 dist/
+docs/_build/
 downloads/
 eggs/
 lib/
diff --git a/README.rst b/README.rst
@@ -34,7 +34,7 @@ version number according
 - Tag-, file-, and callback-based versioning schemas are supported
 - Templates for *tag*, *dev* and *dirty* versions are separated
 - Templates support a lot of substitutions including git and environment information
-- Comprehensive and up-to-date documentation
+- Well-documented
 
 
 See `difference <https://setuptools-git-versioning.readthedocs.io/en/latest/differences.html>`_
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/common_issues/wrong_tag.rst b/docs/common_issues/wrong_tag.rst
@@ -18,4 +18,4 @@ both tag and commit have a creation date, and it is not possible to sort tags by
 
 See also
 ^^^^^^^^
-- :ref:`sort-by-option`
+- :ref:`sort-by-option` option
diff --git a/docs/differences.rst b/docs/differences.rst
diff --git a/docs/install.rst b/docs/install.rst
@@ -1,2 +1,3 @@
+.. _installation:
 .. include:: ../README.rst
   :start-after: install
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+    set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+    echo.
+    echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+    echo.installed, then set the SPHINXBUILD environment variable to point
+    echo.to the full path of the 'sphinx-build' executable. Alternatively you
+    echo.may add the Sphinx directory to PATH.
+    echo.
+    echo.If you don't have Sphinx installed, grab it from
+    echo.http://sphinx-doc.org/
+    exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/options/branch_formatter.rst b/docs/options/branch_formatter.rst
@@ -1,4 +1,5 @@
-.. _branch-formatter-option
+.. _branch-formatter-option:
+
 ``branch_formatter``
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -98,7 +99,7 @@ name and return a properly formatted one:
 Possible values
 ^^^^^^^^^^^^^^^
 
-- None
+- ``None``
 
     Disables this feature
 
diff --git a/docs/options/count_commits.rst b/docs/options/count_commits.rst
@@ -1,14 +1,15 @@
-.. _count-commits-option
+.. _count-commits-option:
+
 ``count_commits_from_version_file``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Used by :ref:`dev-release-file` versioning schema.
 
-Enables feature of tracking commits history for file passed to :ref:`version-file-option`
+Enables feature of tracking commits history for file passed to :ref:`version-file-option` option
 
 .. note::
 
-    This option used only if :ref:`version-file-option` is set.
+    This option used only if :ref:`version-file-option` option is set.
 
 Type
 ^^^^^
diff --git a/docs/options/dev_template.rst b/docs/options/dev_template.rst
@@ -1,4 +1,5 @@
-.. _dev-template-option
+.. _dev-template-option:
+
 ``dev_template``
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -21,5 +22,5 @@ Default value
 
 
 Possible values
-^^^^^^^^
+^^^^^^^^^^^^^^^
 See :ref:`substitutions`
diff --git a/docs/options/dirty_template.rst b/docs/options/dirty_template.rst
@@ -1,4 +1,5 @@
-.. _dirty-template-option
+.. _dirty-template-option:
+
 ``dirty_template``
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -21,5 +22,5 @@ Default value
 
 
 Possible values
-^^^^^^^^
+^^^^^^^^^^^^^^^
 See :ref:`substitutions`
diff --git a/docs/options/enabled.rst b/docs/options/enabled.rst
@@ -1,4 +1,5 @@
-.. _enabled-option
+.. _enabled-option:
+
 ``enabled``
 ~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/options/index.rst b/docs/options/index.rst
@@ -1,4 +1,5 @@
-.. _config-options
+.. _config-options:
+
 Config options
 ---------------
 
diff --git a/docs/options/sort_by.rst b/docs/options/sort_by.rst
@@ -1,4 +1,5 @@
-.. _sort-by-option
+.. _sort-by-option:
+
 ``sort_by``
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -34,9 +35,9 @@ Possible values
 
     .. note::
 
-    See
-    `StackOverflow <https://stackoverflow.com/questions/67206124/what-is-the-difference-between-taggerdate-and-creatordate-for-git-tags>`__
-    for more info.
+        See
+        `StackOverflow <https://stackoverflow.com/questions/67206124/what-is-the-difference-between-taggerdate-and-creatordate-for-git-tags>`__
+        for more info.
 
 - ``"version:refname"`` (alphanumeric sort by tag name)
 
diff --git a/docs/options/starting_version.rst b/docs/options/starting_version.rst
@@ -1,4 +1,5 @@
-.. _starting-version-option
+.. _starting-version-option:
+
 ``starting_version``
 ~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/options/template.rst b/docs/options/template.rst
@@ -1,4 +1,5 @@
-.. _template-option
+.. _template-option:
+
 ``template``
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -26,5 +27,5 @@ Default value
 ``"{tag}"``
 
 Possible values
-^^^^^^^^
+^^^^^^^^^^^^^^^
 See :ref:`substitutions`
diff --git a/docs/options/version_callback.rst b/docs/options/version_callback.rst
@@ -1,4 +1,5 @@
-.. _version_callback-option
+.. _version-callback-option:
+
 ``version_callback``
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -24,7 +25,7 @@ Default value
 Possible values
 ^^^^^^^^^^^^^^^
 
-- None
+- ``None``
 
     Disables this feature
 
diff --git a/docs/options/version_file.rst b/docs/options/version_file.rst
@@ -1,4 +1,5 @@
-.. _version-file-option
+.. _version-file-option:
+
 ``version_file``
 ~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/schemas/callback/index.rst b/docs/schemas/callback/index.rst
@@ -1,4 +1,5 @@
-.. _callback-based-release
+.. _callback-based-release:
+
 Callback-based release
 ~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/schemas/callback/version_callback.rst b/docs/schemas/callback/version_callback.rst
@@ -1,4 +1,5 @@
-.. _version-callback
+.. _version-callback:
+
 Execute some callback function to get current version
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -22,7 +23,7 @@ And there are just no tags in the current branch (``dev``) because all
 of them are placed in the ``master`` branch only.
 
 By default, when you try to get current version, you'll receive some
-initial value (see :ref:`starting-version-option`).
+initial value (see :ref:`starting-version-option` option).
 But if you want to get synchronized version numbers in both on the branches?
 
 You can create a function in some file (for example, in the
@@ -101,4 +102,4 @@ is present**
 
 See also
 """"""""
-- :ref:`version-callback-option`
+- :ref:`version-callback-option` option
diff --git a/docs/schemas/file/dev_release_file.rst b/docs/schemas/file/dev_release_file.rst
@@ -1,4 +1,5 @@
-.. _dev-release-file
+.. _dev-release-file:
+
 Development releases (prereleases) from ``dev`` branch
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -76,7 +77,7 @@ Release process
 
     .. warning::
 
-    Do not place any tags in the ``dev`` branch!
+        Do not place any tags in the ``dev`` branch!
 
 -  Checkout back to ``dev`` branch
 -  Save next release version (e.g. ``1.2.0``) in ``VERSION`` or ``VERSION.txt`` file in the ``dev`` branch.
@@ -88,7 +89,8 @@ Release process
 
     Every change of this file in the ``dev`` branch will lead to this ``N`` suffix to be reset to ``0``. Update this file only in the case when you've setting up the next release version!
 
-.. _dev-release-any-branch-file
+.. _dev-release-any-branch:
+
 Development releases from any branch
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -131,7 +133,8 @@ will generate a version number like ``1.2.3a4``.
 Fifth commit to ``beta`` branch with next release number ``1.2.3``
 will generate a version number like ``1.2.3b5``.
 
-.. _dev-release-ignore-file
+.. _dev-release-ignore-file:
+
 Development releases using just branch name
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -165,7 +168,7 @@ will generate a version number like ``1.0a2``.
 Third commit to ``1.2.beta`` branch
 will generate a version number like ``1.2b3``.
 
-If branch name is not PEP-440 compliant, use :ref:`branch-formatter-option` option
+If branch name is not PEP-440 compliant, use :ref:`branch-formatter-option` option option
 
 .. note::
 
@@ -178,8 +181,8 @@ If branch name is not PEP-440 compliant, use :ref:`branch-formatter-option` opti
 
 See also
 """"""""
-- :ref:`version-file-option`
-- :ref:`count-commits-option`
-- :ref:`dev-template-option`
-- :ref:`dirty-template-option`
-- :ref:`branch-formatter-option`
+- :ref:`version-file-option` option
+- :ref:`count-commits-option` option
+- :ref:`dev-template-option` option
+- :ref:`dirty-template-option` option
+- :ref:`branch-formatter-option` option
diff --git a/docs/schemas/file/index.rst b/docs/schemas/file/index.rst
@@ -1,4 +1,5 @@
-.. _file-based-release
+.. _file-based-release:
+
 File-based release
 ~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/schemas/file/version_file.rst b/docs/schemas/file/version_file.rst
@@ -1,4 +1,5 @@
-.. _version-file
+.. _version-file:
+
 Read some file content as current version
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -68,4 +69,4 @@ is present**
 See also
 """""""""
 - :ref:`version-callback`
-- :ref:`version-file-option`
+- :ref:`version-file-option` option
diff --git a/docs/schemas/tag/dirty_version.rst b/docs/schemas/tag/dirty_version.rst
@@ -1,4 +1,5 @@
-.. _dirty-version
+.. _dirty-version:
+
 *Dirty* version
 ^^^^^^^^^^^^^^^^^^
 
@@ -22,27 +23,8 @@ For example, current repo state is:
 
 And you want to generate post versions for every commit after release tag
 
-You can enable ``setuptools-git-versioning`` for your project in the config file:
-
-- ``setup.py``:
-
-    .. code:: python
-
-        setuptools.setup(
-            ...,
-            setuptools_git_versioning={
-                "enabled": "True",
-            },
-        )
-
-- ``pyproject.toml``:
-
-    .. code:: toml
-
-        [tool.setuptools-git-versioning]
-        enabled = true
-
-And your package version will be ``1.0.0.post1+git.64e68cd4.dirty``.
+Just :ref:`install setuptools-git-versioning <installation>`
+and then your package version will be ``1.0.0.post1+git.64e68cd4.dirty``.
 
 Version number template
 """"""""""""""""""""""""
@@ -74,6 +56,6 @@ To get version in such a format you set a template in the config file:
 
 See also
 """"""""
-- :ref:`dirty-template-option`
+- :ref:`dirty-template-option` option
+- :ref:`sort-by-option` option
 - :ref:`substitutions`
-- :ref:`sort-by-option`
diff --git a/docs/schemas/tag/index.rst b/docs/schemas/tag/index.rst
@@ -1,4 +1,5 @@
-.. _tag-based-release
+.. _tag-based-release:
+
 Tag-based release
 ~~~~~~~~~~~~~~~~~
 
diff --git a/docs/schemas/tag/post_release.rst b/docs/schemas/tag/post_release.rst
diff --git a/docs/schemas/tag/tag_release.rst b/docs/schemas/tag/tag_release.rst
diff --git a/docs/substitutions/branch.rst b/docs/substitutions/branch.rst
diff --git a/docs/substitutions/ccount.rst b/docs/substitutions/ccount.rst
diff --git a/docs/substitutions/env.rst b/docs/substitutions/env.rst
diff --git a/docs/substitutions/full_sha.rst b/docs/substitutions/full_sha.rst
diff --git a/docs/substitutions/index.rst b/docs/substitutions/index.rst
diff --git a/docs/substitutions/sha.rst b/docs/substitutions/sha.rst
diff --git a/docs/substitutions/tag.rst b/docs/substitutions/tag.rst
diff --git a/docs/substitutions/timestamp.rst b/docs/substitutions/timestamp.rst

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
	`1`	`+.. _installation:`
`1`	`2`	`.. include:: ../README.rst`
`2`	`3`	`:start-after: install`