docs(configuration): clarify TOC & standardize heading links

docs/algorithm.rst

@@ -26,7 +26,7 @@ Assumptions
   ``rc``.
 * We know ahead of time whether ``major`` changes introduced by commits
   should cause the new version to remain on ``0.y.z`` if the project is already
-  on a ``0.`` version - see :ref:`major_on_zero <config-major-on-zero>`.
+  on a ``0.`` version - see :ref:`major_on_zero <config-major_on_zero>`.
 
 .. _algorithm-implementation:
 

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 :ref:`config-version-variables` before continuing.
+Make sure that at least you have set :ref:`config-version_variables` before continuing.
 
 2. Add environment variables
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/changelog_templates.rst

@@ -5,20 +5,20 @@ Changelog Templates
 
 .. warning::
     If you have an existing changelog in the location you have configured with
-    the :ref:`changelog_file <config-changelog-changelog-file>` setting,
-    or if you have a template inside your :ref:`template directory <config-changelog-template-dir>`
+    the :ref:`changelog_file <config-changelog-changelog_file>` setting,
+    or if you have a template inside your :ref:`template directory <config-changelog-template_dir>`
     which will render to the location of an existing file, Python Semantic Release will
     overwrite the contents of this file.
 
     Please make sure to refer to :ref:`changelog-templates-migrating-existing-changelog`.
 
 Python Semantic Release can write a changelog for your project. By default, it uses an
 in-built template; once rendered this will be written to the location you configure with the
-:ref:`changelog_file <config-changelog-changelog-file>` setting.
+:ref:`changelog_file <config-changelog-changelog_file>` setting.
 
 However, Python Semantic Release is also capable of rendering an entire directory tree
 of templates during the changelog generation process. This directory is specified
-using the :ref:`template directory <config-changelog-template-dir>` setting.
+using the :ref:`template directory <config-changelog-template_dir>` setting.
 
 Python Semantic Release uses `Jinja`_ as its template engine, so you should refer to the
 `Template Designer Documentation`_ for guidance on how to customize the appearance of
@@ -48,7 +48,7 @@ Directory Structure:
 If you don't want to set up your own custom changelog template, you can have Python
 Semantic Release use its in-built template. If you would like to customize the
 appearance of the changelog, or to render additional files, then you will need to
-create a directory within your repository and set the :ref:`template_dir <config-changelog-template-dir>`
+create a directory within your repository and set the :ref:`template_dir <config-changelog-template_dir>`
 setting to the name of this directory. The default name is ``"templates"``.
 
 .. note::
@@ -78,7 +78,7 @@ a ``"."``.
 Directory Structure (Example)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Suppose a project sets :ref:`template_dir <config-changelog-template-dir>` to
+Suppose a project sets :ref:`template_dir <config-changelog-template_dir>` to
 ``"templates"`` and has the following structure:
 
 .. code-block::
@@ -289,7 +289,7 @@ generates the release notes when :ref:`creating VCS releases <index-creating-vcs
 
 * the `in-built template`_ is used by default
 * create a file named ``.release_notes.md.j2`` inside the project's
-  :ref:`template_dir <config-changelog-template-dir>` to customize the release notes
+  :ref:`template_dir <config-changelog-template_dir>` to customize the release notes
 
 .. _changelog-templates-customizing-vcs-release-notes-release-notes-context:
 

docs/commands.rst

@@ -101,7 +101,7 @@ By default:
 
   * Write this new version to the project metadata locations
     specified in the configuration file
-  * Build the project using :ref:`config-build-command`, if specified
+  * Build the project using :ref:`config-build_command`, if specified
   * Create a new commit with these locations and any other assets configured
     to be included in a release
   * Tag this commit according the configured format, with a tag that uniquely
@@ -116,10 +116,10 @@ commit that is made.
 .. seealso::
     - :ref:`cmd-changelog`
     - :ref:`changelog-templates`
-    - :ref:`config-tag-format`
+    - :ref:`config-tag_format`
     - :ref:`config-assets`
-    - :ref:`config-version-toml`
-    - :ref:`config-version-variables`
+    - :ref:`config-version_toml`
+    - :ref:`config-version_variables`
 
 .. _cmd-version-options:
 
@@ -316,7 +316,7 @@ If ``--no-commit`` is supplied, it may disable other options derivatively; pleas
 **Default:** ``--commit``
 
 .. seealso::
-   - :ref:`tag_format <config-tag-format>`
+   - :ref:`tag_format <config-tag_format>`
 
 .. _cmd-version-option-tag:
 
@@ -370,7 +370,7 @@ implied by supplying only ``--no-commit``), otherwise ``--vcs-release``
 ``--skip-build``
 ****************
 
-If passed, skip building the current project using :ref:`build_command <config-build-command>`.
+If passed, skip building the current project using :ref:`build_command <config-build_command>`.
 
 .. _cmd-publish:
 
@@ -381,7 +381,7 @@ Publish a distribution to a VCS release. Uploads using :ref:`config-publish`
 
 .. seealso::
     - :ref:`config-publish`
-    - :ref:`config-build-command`
+    - :ref:`config-build_command`
 
 .. _cmd-publish-options:
 

docs/commit-parsing.rst

@@ -30,8 +30,8 @@ description to create a major release.
 More information about the style can be found in the `angular commit guidelines`_.
 
 .. seealso::
-  - :ref:`commit_parser <config-commit-parser>`
-  - :ref:`commit_parser_options <config-commit-parser-options>`
+  - :ref:`commit_parser <config-commit_parser>`
+  - :ref:`commit_parser_options <config-commit_parser_options>`
 
 .. _commit-parser-builtin:
 
@@ -181,7 +181,7 @@ If you would prefer to use an alternative commit style, for example to adjust th
 different ``type`` values that are associated with a particular commit, this is
 possible.
 
-The :ref:`commit_parser <config-commit-parser>` option, if set to a string which
+The :ref:`commit_parser <config-commit_parser>` option, if set to a string which
 does not match one of Python Semantic Release's inbuilt commit parsers, will be
 used to attempt to dynamically import a custom commit parser class. As such you will
 need to ensure that your custom commit parser is import-able from the environment in
@@ -296,8 +296,8 @@ To provide options to the commit parser which is configured in the :ref:`configu
 class. Each parser built into Python Semantic Release has a corresponding "options" class, which
 subclasses :py:class:`semantic_release.ParserOptions`.
 
-The configuration in :ref:`commit_parser_options <config-commit-parser-options>` is passed to the
-"options" class which is specified by the configured :ref:`commit_parser <config-commit-parser>` -
+The configuration in :ref:`commit_parser_options <config-commit_parser_options>` is passed to the
+"options" class which is specified by the configured :ref:`commit_parser <config-commit_parser>` -
 more information on how this is specified is below.
 
 The "options" class is used to validate the options which are configured in the repository,