docs: use references where possible

Fixes #221

docs/automatic-releases/github-actions.rst

@@ -50,7 +50,7 @@ Example Workflow
            github_token: ${{ secrets.GITHUB_TOKEN }}
            pypi_token: ${{ secrets.PYPI_TOKEN }}
 
-``PYPI_TOKEN`` should be set as a secret on your repository's settings page.
+:ref:`env-pypi_token` should be set as a secret on your repository's settings page.
 It is also possible to use username and password authentication in a similar
 fashion.
 

docs/automatic-releases/index.rst

@@ -75,8 +75,8 @@ of the build logs.
 Configuring push to Github
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 In order to push to Github and post the changelog to Github the environment variable
-``GH_TOKEN`` has to be set. It needs access to the ``public_repo`` scope for public repositories
-and ``repo`` for private repositories.
+:ref:`env-gh_token` has to be set. It needs access to the ``public_repo`` scope for
+public repositories and ``repo`` for private repositories.
 
 
 Guides

docs/automatic-releases/travis.rst

@@ -8,7 +8,7 @@ If this is not the case, please refer to `Travis documentation`_ on how to do th
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 See :doc:`../configuration` for details on how to configure python-semantic-release.
-Make sure that at least you have set ``version_variable`` before continuing.
+Make sure that at least you have set :ref:`config-version_variable` before continuing.
 
 2. Add environment variables
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -17,7 +17,7 @@ is to go to the settings page for your package and add them there. Make sure tha
 secret toggle is set correct for the ones that are secret.
 
 You will need to set :ref:`env-pypi_token` to a PyPI API token. Furthermore,
-you need to set ``GH_TOKEN`` with a personal access token for Github. It will
+you need to set :ref:`env-gh_token` with a personal access token for Github. It will
 need either ``repo`` or ``public_repo`` scope depending on whether the
 repository is private or public.
 

docs/commands.rst

@@ -11,8 +11,8 @@ When executed this command will print the changelog to stdout.
 
 If the option ``--post`` is used then the program will check if
 there is a authentication token configured for your vcs provider
-(`GH_TOKEN` for github) and it will be posted to the provider
-if supported.
+(:ref:`env-gh_token` for github, :ref:`env-gl_token` for GitLab)
+and it will be posted to the provider if supported.
 
 
 .. _cmd-publish:
@@ -23,9 +23,9 @@ Publish will do a sequence of things.
 
 #. Run same as the :ref:`cmd-version` command
 #. Push changes to git
-#. If ``upload_to_pypi`` is not ``false`` in the :ref:`configuration`
+#. If :ref:`config-upload_to_pypi` is not ``false`` in the :ref:`configuration`
    it will create the wheel and upload to pypi using twine.
-#. If the environment variable ``GH_TOKEN`` (or equivalent for your
+#. If the environment variable :ref:`env-gh_token` (or equivalent for your
    vcs provider) is set then :ref:`cmd-changelog` will be executed and
    the changelog will be posted to your vcs provider if supported.
 

docs/configuration.rst

@@ -17,18 +17,24 @@ Each location has priority over the ones listed above it.
 Releases
 ========
 
+.. _config-branch:
+
 ``branch``
 ----------
 The branch to run releases from.
 
 Default: `master`
 
+.. _config-version_variable:
+
 ``version_variable``
 --------------------
 The file and variable name of where the version number is stored, for example::
 
     semantic_release/__init__.py:__version__
 
+.. _config-version_source:
+
 ``version_source``
 ------------------
 The way we get and set the new version. Can be `commit` or `tag`.
@@ -40,13 +46,17 @@ The way we get and set the new version. Can be `commit` or `tag`.
 
 Default: `commit`
 
+.. _config-commit_parser:
+
 ``commit_parser``
 -----------------
 Import path of a Python function that can parse commit messages and return
 information about the commit as described in :ref:`commit-log-parsing`.
 
 Default: `semantic_release.history.angular_parser`
 
+.. _config-patch_without_tag:
+
 ``patch_without_tag``
 ---------------------
 If this is set to `true`, semantic-release will create a new patch release even if there is
@@ -57,12 +67,16 @@ Default: `false`
 Commits
 =======
 
+.. _config-commit_version_number:
+
 ``commit_version_number``
 -------------------------
 Whether or not to commit changes when bumping version.
 
 Default: True if ``version_source`` is `tag`, False if ``version_source`` is `commit`
 
+.. _config-commit_subject:
+
 ``commit_subject``
 ------------------
 Git commit subject line. Accepts the following variables as format fields:
@@ -75,6 +89,8 @@ Variable          Contents
 
 Default: ``{version}``
 
+.. _config-commit_message:
+
 ``commit_message``
 ------------------
 Git commit message body. Accepts the following variables as format fields:
@@ -87,6 +103,8 @@ Variable          Contents
 
 Default: `Automatically generated by python-semantic-release`
 
+.. _config-commit_author:
+
 ``commit_author``
 -----------------
 Author used in commits in the format ``name <email>``.
@@ -100,6 +118,8 @@ Default: ``semantic-release <semantic-release>``
 Changelog
 =========
 
+.. _config-changelog_sections:
+
 ``changelog_sections``
 -----------------------
 Comma-separated list of sections to display in the changelog.
@@ -119,29 +139,39 @@ Default: `feature, fix, breaking, documentation, performance`
 Distributions
 =============
 
+.. _config-upload_to_pypi:
+
 ``upload_to_pypi``
 ------------------
 If set to false the pypi uploading will be disabled.
 See :ref:`env-pypi_token` which must also be set for this to work.
 
+.. _config-upload_to_release:
+
 ``upload_to_release``
 ---------------------
 If set to false, do not upload distributions to GitHub releases.
 If you are not using GitHub, this will be skipped regardless.
 
+.. _config-dist_path:
+
 ``dist_path``
 -------------
 The relative path to the folder for dists configured for setuptools. This allows for
 customized setuptools processes.
 
 Default: `dist/`
 
+.. _config-remove_dist:
+
 ``remove_dist``
 ---------------
 Flag for whether the dist folder should be removed after a release.
 
 Default: `true`
 
+.. _config-build_command:
+
 ``build_command``
 -----------------
 Command to build dists. Build output should be stored in the directory configured in
@@ -152,12 +182,16 @@ Default: ``python setup.py sdist bdist_wheel``
 HVCS
 ====
 
+.. _config-hvcs:
+
 ``hvcs``
 --------
 The name of your hvcs. Currently only `GitHub` and `GitLab` are supported.
 
 Default: `github`
 
+.. _config-check_build_status:
+
 ``check_build_status``
 ----------------------
 If enabled, the status of the head commit will be checked and a release will only be created