1.26.0: sphinx warnings reference target not found (+79k warnings)

[kloczek]

Describe the bug

sphinx warnings reference target not found

Fiirs of all currently it is not possible to use straight sphinx-build command to build documentation out of source tree

This can be fixed by patch like below:

--- a/docs/source/conf.py~      2022-04-20 18:10:33.000000000 +0000
+++ b/docs/source/conf.py       2022-04-21 20:34:51.278021458 +0000
@@ -11,17 +11,18 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.

-import sys, os
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))
+
 from botocore.session import get_session
 from botocore.docs import generate_docs

 generate_docs(os.path.dirname(os.path.abspath(__file__)), get_session())

-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
-
 # -- General configuration -----------------------------------------------------

 # If your documentation needs a minimal Sphinx version, state it here.

This patch fixes what is in the comment and that cand of fix is suggested in sphinx example copy py https://www.sphinx-doc.org/en/master/usage/configuration.html#example-of-configuration-file

Than .. on building my packages I'm using sphinx-build command with -n switch which shows warmings about missing references. These are not critical issues.

On building my packages I'm using sphinx-build command with -n switch which shows warmings about missing references. These are not critical issues.

Expected Behavior

Sphinx should build documentation without warnings.

Current Behavior

Log is very long. Please find it in attachment
python-botocore-sphinx-build_log.txt

Reproduction Steps

• build module python3 -sBm build -w --no-isolation
• sphinx-build -n -T -b man docs/source build/sphinx/man

Possible Solution

You can peak on fixes that kind of issues in other projects
latchset/jwcrypto#289
click-contrib/sphinx-click@abc31069

I suggest use always -n switch on generate documentation.

Additional Information/Context

N/A

SDK version used

N/A

Environment details (OS name and version, etc.)

Linux x86/64

[tim-finnigan]

Hi @kloczek thanks for reaching out. Sphinx-build is not something we currently support but we can consider this a feature request to add support for it.

[kloczek]

Genarally documentation builds however.
As I'm interested mostly man page I'm not affected to much by those warnings. Most affecter output format in thi case is html.