First of all currently on use straight sphinx-build command to build documentation out of source tree
```console
+ /usr/bin/sphinx-build -n -T -b man doc build/sphinx/man
Running Sphinx v7.3.7
making output directory... done
myst v3.0.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
loading intersphinx inventory from http://www.tornadoweb.org/en/stable/objects.inv...
intersphinx inventory has moved: http://www.tornadoweb.org/en/stable/objects.inv -> https://www.tornadoweb.org/en/stable/objects.inv
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [100%] websocket
WARNING: autodoc: failed to import class 'SingleTermManager' from module 'terminado'; the following exception was raised:
No module named 'terminado'
WARNING: autodoc: failed to import class 'UniqueTermManager' from module 'terminado'; the following exception was raised:
No module named 'terminado'
WARNING: autodoc: failed to import class 'NamedTermManager' from module 'terminado'; the following exception was raised:
No module named 'terminado'
WARNING: autodoc: failed to import class 'TermManagerBase' from module 'terminado'; the following exception was raised:
No module named 'terminado'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-terminado.3 { websocket uimodule changelog } /home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/websocket.rst:4: WARNING: py:class reference target not found: terminado.TermSocket
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/websocket.rst:4: WARNING: py:class reference target not found: tornado.web.WebSocketHandler
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/websocket.rst:24: WARNING: py:class reference target not found: terminado.TermSocket
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/uimodule.rst:25: WARNING: py:class reference target not found: terminado.uimodule.Terminal
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/uimodule.rst:25: WARNING: py:meth reference target not found: terminado.uimodule.Terminal.javascript_files
done
build succeeded, 9 warnings.
```
This can be fixed by patch like below:
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -11,6 +11,7 @@
# All configuration values have a default; values that are commented out
# serve to show the default.
+import os
import shutil
import sys
from pathlib import Path
@@ -21,7 +22,7 @@
# 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 osp.abspath to make it absolute, like shown here.
-# sys.path.insert(0, osp.abspath('.'))
+sys.path.insert(0, os.path.abspath(".."))
# -- General configuration ------------------------------------------------
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.
Here is the output with warnings:
```console
+ /usr/bin/sphinx-build -n -T -b man doc build/sphinx/man
Running Sphinx v7.3.7
making output directory... done
myst v3.0.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
loading intersphinx inventory from http://www.tornadoweb.org/en/stable/objects.inv...
intersphinx inventory has moved: http://www.tornadoweb.org/en/stable/objects.inv -> https://www.tornadoweb.org/en/stable/objects.inv
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [100%] websocket
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-terminado.3 { websocket uimodule changelog } /home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/websocket.rst:4: WARNING: py:class reference target not found: terminado.TermSocket
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/websocket.rst:4: WARNING: py:class reference target not found: tornado.web.WebSocketHandler
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/websocket.rst:24: WARNING: py:class reference target not found: terminado.TermSocket
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/terminado/management.py:docstring of terminado.management.TermManagerBase.get_terminal:1: WARNING: py:class reference target not found: terminado.management.PtyWithClients
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/terminado/management.py:docstring of terminado.management.TermManagerBase.get_terminal:3: WARNING: py:class reference target not found: TermSocket
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/terminado/management.py:docstring of terminado.management.TermManagerBase.new_terminal:1: WARNING: py:class reference target not found: terminado.management.PtyWithClients
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/terminado/management.py:docstring of terminado.management.TermManagerBase.new_terminal:1: WARNING: py:class reference target not found: PtyWithClients
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/terminado/management.py:docstring of terminado.management.TermManagerBase.start_reading:1: WARNING: py:class reference target not found: terminado.management.PtyWithClients
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/uimodule.rst:25: WARNING: py:class reference target not found: terminado.uimodule.Terminal
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/uimodule.rst:25: WARNING: py:meth reference target not found: terminado.uimodule.Terminal.javascript_files
done
build succeeded, 10 warnings.
```
First of all currently on use straight
sphinx-build
command to build documentation out of source treeThis can be fixed by patch like below:
This patch fixes what is in the comment and that can of fix is suggested in sphinx example copy.py https://www.sphinx-doc.org/en/master/usage/configuration.html#example-of-configuration-file
Please let me know if you want above as PR.
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.Here is the output with warnings:
You can peak on fixes that kind of issues in other projects https://github.com/RDFLib/rdflib-sqlalchemy/issues/95 https://github.com/RDFLib/rdflib/pull/2036 https://github.com/click-contrib/sphinx-click/commit/abc31069 https://github.com/frostming/unearth/issues/14 https://github.com/jaraco/cssutils/issues/21 https://github.com/latchset/jwcrypto/pull/289 https://github.com/latchset/jwcrypto/pull/289 https://github.com/pypa/distlib/commit/98b9b89f https://github.com/pywbem/pywbem/pull/2895 https://github.com/sissaschool/elementpath/commit/bf869d9e https://github.com/sissaschool/xmlschema/commit/42ea98f2 https://github.com/sqlalchemy/sqlalchemy/commit/5e88e6e8