Improve docs (#143)

Author: felix-hilden

docs/src/404.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 sphinx-codeautolink
 ===================
 

docs/src/about.rst

@@ -51,6 +51,13 @@ Caveats
 
 Sphinx semantics
 ----------------
+Warnings
+********
+For an easier time with debugging, we recommend enabling all warnings,
+treating them as errors with ``-W`` and only ignoring specific warning types
+with :confval:`suppress_warnings`. This is also easier if
+:confval:`show_warning_types` is set.
+
 Clean build
 ***********
 For correct partial builds, code reference information is saved to a file
@@ -64,6 +71,7 @@ Sphinx cache
 A function specified in :confval:`codeautolink_custom_blocks` prevents Sphinx
 from caching documentation results. Consider using an importable instead.
 For more information, see the discussion in :issue:`76`.
+You can also suppress the warning.
 
 Parallel build and custom parsers
 *********************************

docs/src/conf.py

@@ -32,6 +32,7 @@
 # Builtin options
 html_theme = "sphinx_rtd_theme"
 python_use_unqualified_type_names = True
+show_warning_types = True
 
 # Extension options
 codeautolink_autodoc_inject = True

tox.ini

@@ -60,7 +60,7 @@ commands = pydocstyle src
 description = Build Sphinx documentation
 allowlist_externals = sphinx-build
 change_dir = docs
-commands = sphinx-build -M html src build
+commands = sphinx-build -M html src build -W
 
 [testenv:black-check]
 description = Check code formatting