doc improvements, sphinx 4.2.0

epsy · Nov 8, 2021 · 95bc4cd · 95bc4cd
1 parent b83bbce
commit 95bc4cd
Show file tree

Hide file tree

Showing 4 changed files with 32 additions and 13 deletions.
diff --git a/docs/alternatives.rst b/docs/alternatives.rst
@@ -67,7 +67,7 @@ The above example can be performed using Clize as follows::
 
 .. |ra| replace:: `~argparse.ArgumentParser.add_argument`
 .. |pna| replace:: `~argparse.ArgumentParser.parse_known_args`
-.. |lo| replace:: `~.parser.Parameter.LAST_OPTION`
+.. |lo| replace:: `~clize.Parameter.LAST_OPTION`
 
 +--------------------------------------+--------------------------------------+
 | `argparse`                           | Clize                                |

diff --git a/docs/conf.py b/docs/conf.py
@@ -35,7 +35,14 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', 'sigtools.sphinxext', 'clize._sphinx']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.coverage',
+    'sphinx.ext.viewcode',
+    'sigtools.sphinxext',
+    # 'clize._sphinx',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -51,7 +58,7 @@
 
 # General information about the project.
 project = 'clize'
-copyright = '2013-2016, Yann Kaiser'
+copyright = '2013-2021, Yann Kaiser'
 
 
 
@@ -92,6 +99,14 @@
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 default_role = 'py:obj'
+nitpicky = True
+nitpick_ignore_regex = [
+    (r'py:.*', r'^sequence.*'),
+    (r'py:.*', r'^iterable.*'),
+    (r'py:.*', r'^file$'),
+    (r'py:.*', r'^function$'),
+    (r'py:.*', r'^callable$'),
+]
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
@@ -268,9 +283,9 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'python': ('http://docs.python.org/3/', None),
-    'sigtools': ('http://sigtools.readthedocs.io/en/latest/', None),
-    'sphinx': ('http://www.sphinx-doc.org/en/stable/', None),
+    'python': ('https://docs.python.org/3/', None),
+    'sigtools': ('https://sigtools.readthedocs.io/en/latest/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/stable/', None),
     }
 
 autoclass_content = 'both'

diff --git a/docs/reference.rst b/docs/reference.rst
@@ -177,7 +177,7 @@ does not handle strings, unless you specify a converter::
 Ignoring the source parameter's default value
 .............................................
 
-.. moreattribute:: Parameter.REQUIRED
+.. attribute:: clize.Parameter.REQUIRED
 
     Annotate a parameter with this to force it to be required, even if there
     is a default value in the source.
@@ -249,7 +249,7 @@ on the CLI:
         args ('two', 'three')
 
 
-.. moreattribute:: Parameter.REQUIRED
+.. attribute:: clize.Parameter.REQUIRED
 
     When used on an ``*args`` parameter, requires at least one value to be
     provided.
@@ -573,7 +573,7 @@ Callables decorated with `clize.parser.parameter_converter` are used
 instead of the :ref:`default converter <default-converter>` to construct a
 CLI parameter for the annotated Python parameter.
 
-The callable can return a `Parameter` instance or `Parameter.IGNORE` to
+The callable can return a `Parameter` instance or `Parameter.IGNORE <clize.Parameter.IGNORE>` to
 instruct clize to drop the parameter.
 
 ::
@@ -616,7 +616,7 @@ converter<parameter converters>` is recommended over this.
 Skipping parameters
 ...................
 
-.. automoreattribute:: Parameter.IGNORE
+.. autoattribute:: clize.Parameter.IGNORE
 
     Note that it is dangerous to use this on anything except:
 
@@ -655,7 +655,7 @@ Skipping parameters
 Hiding parameters from the help
 ...............................
 
-.. automoreattribute:: Parameter.UNDOCUMENTED
+.. autoattribute:: clize.Parameter.UNDOCUMENTED
 
     ::
 
@@ -680,7 +680,7 @@ Hiding parameters from the help
 Forcing arguments to be treated as positional
 .............................................
 
-.. automoreattribute:: Parameter.LAST_OPTION
+.. autoattribute:: clize.Parameter.LAST_OPTION
 
     ::
 

diff --git a/tox.ini b/tox.ini
@@ -30,7 +30,7 @@ deps=
     pathlib2
     python-dateutil
     Pygments
-    docs: sphinx
+    docs: sphinx~=4.2.0
     docs: sphinx_rtd_theme
     cover: coverage~=5.5
     cover: coveralls~=3.2.0
@@ -48,6 +48,10 @@ commands=
     cover-help: coverage report --include 'clize/help.py'
     docs: {envbindir}/sphinx-build {toxinidir}/docs/ {toxinidir}/build/sphinx {posargs:}
 
+
+[testenv:docs]
+basepython=python3.9
+
 [testenv:coveralls]
 passenv=TRAVIS TRAVIS_*
 commands=