Updated docs.

Author: domdfcoding

doc-source/api/pagesizes/index.rst

@@ -2,11 +2,12 @@
 :mod:`domdf_python_tools.pagesizes`
 =========================================
 
+.. automodule:: domdf_python_tools.pagesizes
+	:no-members:
+
+
 .. toctree::
 	:caption: Submodules
 	:glob:
 
 	*
-
-.. automodule:: domdf_python_tools.pagesizes
-	:undoc-members:

doc-source/autodoc_augment_defaults.py

@@ -7,9 +7,6 @@
 import re
 import sys
 
-# 3rd party
-from sphinx.locale import _
-
 sys.path.append(os.path.abspath('.'))
 sys.path.append(os.path.abspath('..'))
 
@@ -37,26 +34,27 @@
 package_root = "domdf_python_tools"
 
 extensions = [
-	'sphinx.ext.intersphinx',
-	'sphinx.ext.autodoc',
-	'sphinx.ext.mathjax',
-	'sphinx.ext.viewcode',
-	'sphinxcontrib.httpdomain',
-	'sphinxcontrib.extras_require',
-	'sphinx.ext.todo',
-	'sphinxemoji.sphinxemoji',
+	'autodocsumm',
 	'notfound.extension',
-	'sphinx_tabs.tabs',
+	'seed_intersphinx_mapping',
 	'sphinx-prompt',
+	'sphinx.ext.autodoc',
+	'sphinx.ext.autosectionlabel',
 	'sphinx.ext.autosummary',
-	'autodocsumm',
+	'sphinx.ext.intersphinx',
+	'sphinx.ext.mathjax',
+	'sphinx.ext.todo',
+	'sphinx.ext.viewcode',
+	'sphinx_autodoc_typehints',
 	'sphinx_copybutton',
+	'sphinx_tabs.tabs',
+	'sphinx_toolbox',
+	'sphinx_toolbox.autodoc_augment_defaults',
 	'sphinxcontrib.default_values',
+	'sphinxcontrib.extras_require',
+	'sphinxcontrib.httpdomain',
 	'sphinxcontrib.toctree_plus',
-	'seed_intersphinx_mapping',
-	'autodoc_augment_defaults',
-	'sphinx.ext.autosectionlabel',
-	'sphinx_autodoc_typehints',
+	'sphinxemoji.sphinxemoji',
 	]
 
 sphinxemoji_style = 'twemoji'
@@ -127,31 +125,3 @@
 				"__hash__",
 				]),
 		}
-
-
-# Extensions to theme docs
-def setup(app):
-	from sphinx.domains.python import PyField
-	from sphinx.util.docfields import Field
-
-	app.add_object_type(
-			'confval',
-			'confval',
-			objname='configuration value',
-			indextemplate='pair: %s; configuration value',
-			doc_field_types=[
-					PyField(
-							'type',
-							label=_('Type'),
-							has_arg=False,
-							names=('type', ),
-							bodyrolename='class',
-							),
-					Field(
-							'default',
-							label=_('Default'),
-							has_arg=False,
-							names=('default', ),
-							),
-					]
-			)

doc-source/conf.py

@@ -116,34 +116,12 @@ Installation
 
 .. start installation
 
-.. tabs::
+.. installation:: domdf_python_tools
+	:pypi:
+	:github:
+	:anaconda:
+	:conda-channels: domdfcoding, conda-forge
 
-	.. tab:: from PyPI
-
-		.. prompt:: bash
-
-			python3 -m pip install domdf_python_tools --user
-
-	.. tab:: from Anaconda
-
-		First add the required channels
-
-		.. prompt:: bash
-
-			conda config --add channels http://conda.anaconda.org/domdfcoding
-			conda config --add channels http://conda.anaconda.org/conda-forge
-
-		Then install
-
-		.. prompt:: bash
-
-			conda install domdf_python_tools
-
-	.. tab:: from GitHub
-
-		.. prompt:: bash
-
-			python3 -m pip install git+https://github.com/domdfcoding/domdf_python_tools@master --user
 
 .. end installation
 

doc-source/index.rst

@@ -1,15 +1,15 @@
 autodocsumm>=0.2.0
 default_values>=0.0.8
-domdf_sphinx_theme>=0.0.11
+domdf_sphinx_theme>=0.1.0
 extras_require
-pytz>=2019.1
-seed_intersphinx_mapping>=0.1.0
+seed_intersphinx_mapping>=0.1.1
 sphinx>=3.0.3
 sphinx-copybutton>=0.2.12
 sphinx-notfound-page
 sphinx-prompt>=1.2.0
 sphinx-tabs>=1.1.13
+sphinx-toolbox>=0.1.0
 sphinxcontrib-httpdomain>=1.7.0
 sphinxemoji>=0.1.6
-toctree_plus>=0.0.2
+toctree_plus>=0.0.3
 git+git://github.com/domdfcoding/sphinx-autodoc-typehints.git@typevar-as-pydata

doc-source/requirements.txt

@@ -4,7 +4,7 @@
 """
 Functions for working with secrets, such as API tokens.
 
-..versionadded:: 0.4.6
+.. versionadded:: 0.4.6
 """
 #
 #  Copyright © 2020 Dominic Davis-Foster <[email protected]>
@@ -44,7 +44,7 @@ class Secret(str):
 			>>> Secret("Barry as FLUFL") == "Barry as FLUFL"
 			True
 
-	..versionadded:: 0.4.6
+	.. versionadded:: 0.4.6
 	"""
 
 	value: str  #: The actual value of the secret.

domdf_python_tools/secrets.py

@@ -149,9 +149,7 @@ def get_terminal_size() -> Tuple[int, int]:  # pragma: no cover
 
 	Works on Linux, macOS, Windows, and Cygwin.
 
-	Based on http://stackoverflow.com/questions/566746/how-to-get-console-window-width-in-python
-
-	:return: tuple_xy
+	:return: Screen width and screen height.
 	"""
 
 	current_os = platform.system()
@@ -249,7 +247,6 @@ class Echo:
 	Context manager for echoing variable assignments (in CPython).
 
 	:param indent: The indentation of the dictionary of variable assignments.
-	:type indent: str, optional
 	"""
 
 	def __init__(self, indent: str = "  "):
@@ -262,9 +259,17 @@ def __init__(self, indent: str = "  "):
 			self.parent_frame = inspect.currentframe().f_back  # type: ignore  # TODO
 
 	def __enter__(self):
+		"""
+		Called when entering the context manager.
+		"""
+
 		self.locals_on_entry = self.parent_frame.f_locals.copy()  # type: ignore
 
-	def __exit__(self, exc_t, exc_v, tb):
+	def __exit__(self, *args, **kwargs):
+		"""
+		Called when exiting the context manager.
+		"""
+
 		new_locals = {
 				k: v
 				for k,

domdf_python_tools/terminal.py

@@ -140,7 +140,7 @@ def cmp(x, y) -> int:
 
 	Compare the two objects x and y and return an integer according to the outcome.
 
-	The return value is negative if x < y, zero if x == y and strictly positive if x > y.
+	The return value is negative if ``x < y``, zero if ``x == y`` and strictly positive if ``x > y``.
 	"""
 
 	return int((x > y) - (x < y))
@@ -199,7 +199,7 @@ def printt(obj: Any, *args, **kwargs) -> None:
 	print(type(obj), *args, **kwargs)
 
 
-def stderr_writer(*args, **kwargs):
+def stderr_writer(*args, **kwargs) -> None:
 	"""
 	Write to stderr, flushing stdout beforehand and stderr afterwards.
 	"""
@@ -239,7 +239,7 @@ def str2tuple(input_string: str, sep: str = ',') -> Tuple[int, ...]:
 
 		The input string must represent a comma-separated series of integers.
 
-	TODO: Allow custom types, not just ``int`` (making ``int`` the default)
+	.. TODO:: Allow custom types, not just ``int`` (making ``int`` the default)
 
 	:param input_string: The string to be converted into a tuple
 	:type input_string: str
@@ -277,9 +277,10 @@ def strtobool(val: Union[str, bool]) -> bool:
 
 def enquote_value(value: Any) -> Union[str, bool, float]:
 	"""
-	Adds quotes to the given value, suitable for use in a templating system such as Jinja2.
+	Adds quotes (``'``) to the given value, suitable for use in a templating system such as Jinja2.
 
-	floats, integers, booleans, None, and the strings "True", "False" and "None" are returned as-is.
+	:class:`Floats <float>`, :class:`integers <int>`, :class:`booleans <bool>`, :py:obj:`None`,
+	and the strings ``'True'``, ``'False'`` and ``'None'`` are returned as-is.
 
 	:param value: The value to enquote
 	"""

domdf_python_tools/utils.py

@@ -4,7 +4,7 @@
 """
 Functions for working with (English) words.
 
-..versionadded:: 0.4.5
+.. versionadded:: 0.4.5
 """
 # stdlib
 #
@@ -44,7 +44,6 @@
 import domdf_python_tools
 from domdf_python_tools.paths import PathPlus
 
-
 __all__ = ["get_words_list", "get_random_word"]
 
 
@@ -60,7 +59,7 @@ def get_words_list(min_length: int = 0, max_length: int = -1) -> List[str]:
 
 	:return: The list of words meeting the above specifiers.
 
-	..versionadded:: 0.4.5
+	.. versionadded:: 0.4.5
 	"""
 
 	with importlib_resources.path(domdf_python_tools, "google-10000-english-no-swears.txt") as words_file_:
@@ -88,7 +87,7 @@ def get_random_word(min_length: int = 0, max_length: int = -1) -> str:
 
 	:return: A random word meeting the above specifiers.
 
-	..versionadded:: 0.4.5
+	.. versionadded:: 0.4.5
 	"""
 
 	words_list = get_words_list(min_length=min_length, max_length=max_length)