Merge pull request #1122 from adamtheturtle/sphinx-substitution

Use sphinx-substitution-extensions to have fewer references to the gi…

Author: adamtheturtle

dev-requirements.txt

@@ -1,3 +1,8 @@
+PyYAML==5.2
+Pygments==2.5.2
+Sphinx-Substitution-Extensions==2019.6.15.0
+Sphinx==2.2.2
+VWS-Python-Mock==2019.9.28.0
 autoflake==1.3.1
 check-manifest==0.40
 codecov==2.0.15 # Upload coverage data
@@ -14,17 +19,13 @@ pip_check_reqs==2.0.3
 pydocstyle==4.0.1  # Lint docstrings
 pyenchant==2.0.0  # Bindings for a spellchecking sytem
 pygithub==1.44.1
-Pygments==2.5.2
 pylint==2.4.4  # Lint
 pyroma==2.6  # Packaging best practices checker
 pytest-cov==2.8.1  # Measure code coverage
 pytest==5.3.1  # Test runners
-PyYAML==5.2
-Sphinx==2.2.2
 sphinx-autodoc-typehints==1.10.3
 sphinxcontrib-spelling==4.3.0
 twine==3.1.1
 versioneer==0.18
 vulture==1.2
-VWS-Python-Mock==2019.9.28.0
 yapf==0.29.0  # Automatic formatting for Python

docs/source/conf.py

@@ -25,6 +25,7 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'sphinx_autodoc_typehints',
+    'sphinx_substitution_extensions',
     'sphinxcontrib.spelling',
 ]
 
@@ -57,6 +58,12 @@
 version = vws.__version__
 release = version.split('+')[0]
 
+substitutions = [
+    ('|release|', release),
+    ('|github-owner|', 'adamtheturtle'),
+    ('|github-repository|', 'vws-python'),
+]
+
 language = None
 
 # The name of the syntax highlighting style to use.

docs/source/contributing.rst

@@ -12,20 +12,20 @@ Install contribution dependencies
 
 Install Python dependencies in a virtual environment.
 
-.. code:: sh
+.. substitution-prompt:: bash
 
     pip install --editable '.[dev]'
 
 Spell checking requires ``enchant``.
 This can be installed on macOS, for example, with `Homebrew <https://brew.sh>`__:
 
-.. code:: sh
+.. substitution-prompt:: bash
 
     brew install enchant
 
 and on Ubuntu with ``apt``:
 
-.. code:: sh
+.. substitution-prompt:: bash
 
     apt-get install -y enchant
 
@@ -34,13 +34,13 @@ Linting
 
 Run lint tools:
 
-.. code:: sh
+.. substitution-prompt:: bash
 
     make lint
 
 To fix some lint errors, run the following:
 
-.. code:: sh
+.. substitution-prompt:: bash
 
     make fix-lint
 
@@ -49,7 +49,7 @@ Running tests
 
 Run ``pytest``:
 
-.. code:: sh
+.. substitution-prompt:: bash
 
     pytest
 
@@ -60,7 +60,7 @@ Documentation is built on Read the Docs.
 
 Run the following commands to build and view documentation locally:
 
-.. code:: sh
+.. substitution-prompt:: bash
 
    make docs
    make open-docs

docs/source/index.rst

@@ -4,7 +4,7 @@
 Installation
 ------------
 
-.. code:: sh
+.. substitution-prompt:: bash
 
    pip3 install vws-python
 
@@ -57,7 +57,7 @@ Testing
 
 To write unit tests for code which uses this library, without using your Vuforia quota, you can use the `VWS Python Mock`_ tool:
 
-.. code:: sh
+.. substitution-prompt:: bash
 
    pip3 install vws-python-mock
 

docs/source/release-process.rst

@@ -24,7 +24,7 @@ Perform a Release
 
    E.g.:
 
-   .. code:: sh
+   .. substitution-prompt:: bash
 
       curl https://raw.githubusercontent.com/mitsuhiko/pipsi/master/get-pipsi.py | python
       pipsi install keyring
@@ -46,7 +46,7 @@ Add the following information to :file:`~/.pypirc`.
 
 Store your PyPI password:
 
-.. code:: sh
+.. substitution-prompt:: bash
 
    keyring set https://upload.pypi.org/legacy/ <Your PyPI username>
 
@@ -56,15 +56,15 @@ Store your PyPI password:
 
 #. Set environment variables to GitHub credentials, e.g.:
 
-    .. code:: sh
+    .. substitution-prompt:: bash
 
        export GITHUB_TOKEN=75c72ad718d9c346c13d30ce762f121647b502414
-       export GITHUB_OWNER=adamtheturtle
 
 #. Perform a release:
 
-    .. code:: sh
+    .. substitution-prompt:: bash
 
-       curl https://raw.githubusercontent.com/"$GITHUB_OWNER"/vws-python/master/admin/release.sh | bash
+       export GITHUB_OWNER=|github-owner|
+       curl https://raw.githubusercontent.com/"$GITHUB_OWNER"/|github-repository|/master/admin/release.sh | bash
 
 .. _GitHub access token instructions: https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line/