Add some basic troubleshooting tips for the docs build

Author: lethosor

docs/dev/Documentation.rst

@@ -67,6 +67,8 @@ with relevant tags. These are used to compile indices and generate cross-links b
 commands, both in the HTML documents and in-game. See the list of available `tag-list` and
 think about which categories your new tool belongs in.
 
+.. _docs-links:
+
 Links
 -----
 
@@ -498,6 +500,48 @@ folder. Also be aware that when running ``sphinx-build`` directly, the
 ``docs/html`` folder may be polluted with intermediate build files that normally
 get written in the cmake ``build`` directory.
 
+Troubleshooting
+===============
+
+Sphinx errors are typically printed by Sphinx, so ensure that you are not silencing Sphinx output.
+
+When built with ``docs/build.py`` or CMake, errors are also logged to
+``build/docs/<format>/sphinx-warnings.txt`` (for instance, if you are building
+the HTML docs, ``build/docs/html/sphinx-warnings.txt``).
+
+
+"undefined label"
+-----------------
+
+Typical causes:
+
+* You have used single backticks for an inline code snippet, where double backticks should be used instead (see `docs-links`)::
+
+    `this is an invalid inline code snippet (actually a link)`
+    ``this is a valid inline code snippet``
+
+* You are attempting to link to a section/label, but either it does not have a label defined or you have spelled it incorrectly::
+
+    .. my-label:
+
+    This is where the link should go to.
+
+    ...
+
+    This is `a valid link to the earlier label <my-label>`. So is `my-label`.
+
+"toctree contains reference to document that doesn't have a title"
+------------------------------------------------------------------
+
+Due to the nature of our autogenerated documentation, this can sometimes occur
+when switching between branches that have different autogenerated files, and can
+result in autogenerated documentation (e.g. for individual tools) being missing
+from the table of contents, or links failing to generate.
+
+The quickest resolution is a clean docs build::
+
+    docs/build.py --clean
+
 .. _build-changelog:
 
 Building the changelogs