From bf869d9e665b92666ff4c55f79a4efeab1c64285 Mon Sep 17 00:00:00 2001
From: Davide Brunato <brunato@sissa.it>
Date: Mon, 30 May 2022 14:23:16 +0200
Subject: [PATCH] Fix sphinx warnings (issue #45)

  - Set autodoc_typehints = 'none' in conf.py (for the moment,
    type aliases expansion is huge, reconsider for the v3.0.0
    after a refactoring of type hints)
---
 doc/conf.py                           | 12 +++++++++---
 doc/xpath_api.rst                     |  9 ++++++---
 elementpath/xpath30/xpath30_parser.py |  4 ++--
 elementpath/xpath_selectors.py        |  3 ++-
 tox.ini                               |  1 +
 5 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index 8eede28e..7703aab2 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -48,8 +48,13 @@
     'sphinx.ext.doctest',
 ]
 
-# Option for autodoc: do not add module name as prefix to classes or functions.
-add_module_names = False
+# Options for autodoc
+add_module_names = False  # do not add module name as prefix to classes or functions.
+autodoc_typehints = 'none'  # do not add type annotations
+
+nitpick_ignore = [
+    ('py:class', 'XMLSchemaProxy')
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -68,7 +73,8 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+# language = None
+language = 'en'  # required by Sphinx v5.0.0
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
diff --git a/doc/xpath_api.rst b/doc/xpath_api.rst
index 8404ab37..d1d4ee24 100644
--- a/doc/xpath_api.rst
+++ b/doc/xpath_api.rst
@@ -90,7 +90,7 @@ XML Schema proxy
 
 The XPath 2.0 parser can be interfaced with an XML Schema processor through a schema proxy.
 An :class:`XMLSchemaProxy` class is defined for interfacing schemas created with the *xmlschema* package.
-This class is based on an abstract class :class:`AbstractSchemaProxy`, that can be used for
+This class is based on an abstract class :class:`elementpath.AbstractSchemaProxy`, that can be used for
 implementing concrete interfaces to other types of XML Schema processors.
 
 .. autoclass:: elementpath.AbstractSchemaProxy
@@ -110,7 +110,10 @@ implementing concrete interfaces to other types of XML Schema processors.
 XPath nodes
 ===========
 
-XPath nodes are processed using a set of classes derived from :class:`XPathNode`:
+XPath nodes are processed using a set of classes derived from
+:class:`elementpath.XPathNode`:
+
+.. autoclass:: elementpath.XPathNode
 
 .. autoclass:: elementpath.AttributeNode
 .. autoclass:: elementpath.TextNode
@@ -133,7 +136,7 @@ Exception classes
 .. autoexception:: elementpath.RegexError
 
 There are also other exceptions, multiple derived from the base exception
-:class:`ElementPathError` and Python built-in exceptions:
+:class:`elementpath.ElementPathError` and Python built-in exceptions:
 
 .. autoexception:: elementpath.ElementPathKeyError
 .. autoexception:: elementpath.ElementPathLocaleError
diff --git a/elementpath/xpath30/xpath30_parser.py b/elementpath/xpath30/xpath30_parser.py
index 54dee4f5..f74c519f 100644
--- a/elementpath/xpath30/xpath30_parser.py
+++ b/elementpath/xpath30/xpath30_parser.py
@@ -30,9 +30,9 @@ class XPath30Parser(XPath2Parser):
     arguments, but the *strict* option is ignored because XPath 3.0+ has braced
     URI literals and the expanded name syntax is not compatible.
 
-    :param args: the same positional arguments of class :class:`XPath2Parser`.
+    :param args: the same positional arguments of class :class:`elementpath.XPath2Parser`.
     :param decimal_formats: a mapping with statically known decimal formats.
-    :param kwargs: the same keyword arguments of class :class:`XPath2Parser`.
+    :param kwargs: the same keyword arguments of class :class:`elementpath.XPath2Parser`.
     """
     version = '3.0'
 
diff --git a/elementpath/xpath_selectors.py b/elementpath/xpath_selectors.py
index 72d5cd91..a97a3b7a 100644
--- a/elementpath/xpath_selectors.py
+++ b/elementpath/xpath_selectors.py
@@ -8,6 +8,7 @@
 # @author Davide Brunato <brunato@sissa.it>
 #
 from typing import TYPE_CHECKING, Any, Dict, Optional, Iterator, Union, Type
+import typing
 
 from .namespaces import NamespacesType
 from .xpath_context import ContextRootType, XPathContext
@@ -17,7 +18,7 @@
     from .xpath1 import XPath1Parser
     from .xpath30 import XPath30Parser
 
-    ParserType = Union[Type[XPath1Parser], Type[XPath2Parser], Type[XPath30Parser]]
+    ParserType = typing.Union[Type[XPath1Parser], Type[XPath2Parser], Type[XPath30Parser]]
 else:
     ParserType = XPath2Parser
 
diff --git a/tox.ini b/tox.ini
index 1c52010c..9537710d 100644
--- a/tox.ini
+++ b/tox.ini
@@ -29,6 +29,7 @@ commands =
     make -C doc html
     make -C doc latexpdf
     make -C doc doctest
+    sphinx-build -n -T -b man doc build/sphinx/man
 
 [flake8]
 max-line-length = 100