deploy: 34e7264

2.1/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 64b8f72ebbc33a2e29eb330afd3a50a6
+tags: 645f666f9bcd5a90fca523b33c5a78b7

2.1/_sources/explanations/how-it-works.rst.txt

@@ -0,0 +1,71 @@
+How it works
+============
+
+The commandline ``versiongit`` tool can be used to place a ``_version_git.py``
+in your repository. This produces a sensible PEP440 compliant version number
+accessible as ``yourmodule.__version__``. The two ways it gets this information
+are documented below.
+
+From Git
+~~~~~~~~
+
+At development time when running from a Git repository, the ``git describe``
+command is used to work out the version number of the module. If the module
+is on a tag, the version name will just be the tag name, otherwise it will
+be suffixed with the number of commits since a tag and the sha1. This
+``__version__`` variable can then be imported into your module namespace with
+a ``from _version_git import __version__`` statement in the top level
+``__init__.py``:
+
+.. digraph:: from_git
+
+    bgcolor=transparent
+    node [fontname=Arial fontsize=10 shape=box style=filled fillcolor="#f54d27"]
+    edge [fontname=Arial fontsize=10 arrowhead=vee]
+
+    vgv [label="yourmodule._version_git.__version__"]
+    vg [label="yourmodule._version_git.get_version_from_git"]
+    Git
+    v [label="yourmodule.__version__"]
+
+    vgv -> vg [label="get_version_from_git()"]
+    vg -> Git [label="describe --tags ..."]
+    Git -> vg [label="0.1-3-gabc1234"]
+    vg -> vgv [label="0.1+3.abc1234"]
+    vgv -> v [label="0.1+3.abc1234"]
+
+Static Version
+~~~~~~~~~~~~~~
+
+There are two times when we can't get the version number from git:
+
+1) When running from a source archive produced by a ``git archive`` command
+2) When running from an installed sdist, egg or wheel
+
+To handle the first case, ``_version_git.py`` contains a ``GIT_REFS`` variable
+that will be substituted by the ``git archive`` command. This will contain the
+tag name among other things.
+
+For the second case, ``_version_git.py`` contains some command classes that can
+be used in ``setup.py`` when creating an ``sdist``, ``bidst_egg`` or
+``bdist_wheel``. These command classes substitute the ``GIT_REFS`` variable in
+the distribution, replacing it with the static version from Git.
+
+Both cases produce a ``_version_git.py`` that computes the version number from
+``GIT_REFS`` rather than from a ``git`` command:
+
+.. digraph:: static_version
+
+    bgcolor=transparent
+    node [fontname=Arial fontsize=10 shape=box style=filled fillcolor="#f54d27"]
+    edge [fontname=Arial fontsize=10 arrowhead=vee]
+
+    vgv [label="yourmodule._version_git.__version__"]
+    vga [label="yourmodule._version_git.GIT_REFS"]
+    vg [label="yourmodule._version_git.get_version_from_git"]
+    v [label="yourmodule.__version__"]
+
+    vgv -> vg [label="get_version_from_git()"]
+    vga -> vg [label="tag: 0.1"]
+    vg -> vgv [label="0.1"]
+    vgv -> v [label="0.1"]

2.1/_sources/how-to/make-a-release.rst.txt

@@ -0,0 +1,14 @@
+Make a Release
+==============
+
+Git tag with a PEP440 compliant version number.
+
+Version numbers are taken from the git tag. These tags must be of the format
+[0-9]*[-.][0-9]* and dashes will be converted to dots. E.g.:
+
+- 0.1.6
+- 4.3b3
+- 3-4 (converted to 3.4)
+
+Tags not of this format will be ignored.
+

2.1/_sources/index.rst.txt

@@ -0,0 +1,67 @@
+.. include:: ../README.rst
+    :end-before: when included in index.rst
+
+How the documentation is structured
+-----------------------------------
+
+Documentation is split into four categories, accessible from links in the side-bar.
+
+.. rst-class:: columns
+
+Tutorials
+~~~~~~~~~
+
+Tutorials for installation, library and commandline usage. New users start here.
+
+.. toctree::
+    :caption: Tutorials
+    :hidden:
+
+    tutorials/installation
+
+.. rst-class:: columns
+
+How-to Guides
+~~~~~~~~~~~~~
+
+Practical step-by-step guides for the more experienced user.
+
+.. toctree::
+    :caption: How-to Guides
+    :hidden:
+
+    how-to/make-a-release
+
+.. rst-class:: columns
+
+Explanations
+~~~~~~~~~~~~
+
+Explanation of how the library works and why it works that way.
+
+.. toctree::
+    :caption: Explanations
+    :hidden:
+
+    explanations/how-it-works
+
+.. rst-class:: columns
+
+Reference
+~~~~~~~~~
+
+Technical reference material, for classes, methods, APIs, commands, and contributing to the project.
+
+.. toctree::
+    :caption: Reference
+    :hidden:
+
+    reference/version-number-format
+    reference/contributing
+
+.. rst-class:: endcolumns
+
+About the documentation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+`Why is the documentation structured this way? <https://documentation.divio.com>`_

2.1/_sources/reference/contributing.rst.txt

@@ -0,0 +1,3 @@
+.. _contributing:
+
+.. include:: ../../CONTRIBUTING.rst

2.1/_sources/reference/version-number-format.rst.txt

@@ -0,0 +1,17 @@
+Version Number Format
+=====================
+
+Git tags in the format given by `../how-to/make-a-release` will generate version numbers
+
+=========================== =============================
+Version Number              Meaning
+=========================== =============================
+TAG                         On a git tag, so is a released version TAG
+TAG+DISTANCE.gHASH[.dirty]  DISTANCE commits since released version TAG, with
+                            the last commit being HASH. If dirty, then
+                            uncommitted changes have been made to the source tree
+0.0+untagged.gHASH[.dirty]  Cannot find a previous tag. The last commit is HASH.
+                            If dirty, then there are uncommitted changes
+0.0+unknown                 Cannot determine version from git
+=========================== =============================
+

2.1/_sources/tutorials/installation.rst.txt

@@ -0,0 +1,59 @@
+Installation Tutorial
+=====================
+
+.. note::
+
+    For installation inside DLS, please see the internal documentation on
+    ``dls-python3`` and ``pipenv``. Although these instructions will work
+    inside DLS, they are intended for external use.
+
+    If you want to contribute to the library itself, please follow
+    the `contributing` instructions.
+
+Check your version of python
+----------------------------
+
+You will need python 3.6 or greater. You can check your version of python by
+typing into a terminal::
+
+    python3 --version
+
+Create a virtual environment
+----------------------------
+
+It is recommended that you install into a “virtual environment” so this
+installation will not interfere with any existing Python software::
+
+    python3 -m venv /path/to/venv
+    source /path/to/venv/bin/activate
+
+
+Installing the library
+----------------------
+
+You can now use ``pip`` to install the library::
+
+    python3 -m pip install versiongit
+
+If you require a feature that is not currently released you can also install
+from github::
+
+    python3 -m pip install git+git://github.com/dls-controls/versiongit.git
+
+The library should now be installed and the commandline interface on your path.
+You can check the version that has been installed by typing::
+
+    versiongit --version
+
+
+Add VersionGit to your package
+------------------------------
+
+You can then use the commandline ``versiongit`` tool to install a
+``_version_git.py`` into the python package you wish to version::
+
+    versiongit repo/packagename
+
+This will create ``repo/packagename/_version_git.py`` and tell you what to put in
+``repo/setup.py``, ``repo/packagename/__init__.py`` and ``repo/.gitattributes``
+to make it work