From 172e8c7698db62bd315247d7802ab14b68c375ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20Hild=C3=A9n?= Date: Mon, 3 Jun 2024 19:06:58 +0300 Subject: [PATCH] Improve docs (#143) --- docs/src/404.rst | 2 ++ docs/src/about.rst | 8 ++++++++ docs/src/conf.py | 1 + tox.ini | 2 +- 4 files changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/src/404.rst b/docs/src/404.rst index 3c5049d..96709c2 100644 --- a/docs/src/404.rst +++ b/docs/src/404.rst @@ -1,3 +1,5 @@ +:orphan: + sphinx-codeautolink =================== diff --git a/docs/src/about.rst b/docs/src/about.rst index fcb14eb..165366e 100644 --- a/docs/src/about.rst +++ b/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 ********************************* diff --git a/docs/src/conf.py b/docs/src/conf.py index fb8bcc0..a45ea81 100644 --- a/docs/src/conf.py +++ b/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 diff --git a/tox.ini b/tox.ini index 62c2008..05cf3a7 100644 --- a/tox.ini +++ b/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