Updated documentation.

Author: domdfcoding

doc-source/api/terminal_colours.rst

@@ -4,3 +4,4 @@
 
 .. automodule:: domdf_python_tools.terminal_colours
 	:members:
+	:autosummary:

doc-source/conf.py

@@ -53,7 +53,7 @@
 		]
 
 sphinxemoji_style = 'twemoji'
-todo_include_todos = bool(os.environ.get("SHOW_TODOS", False))
+todo_include_todos = bool(os.environ.get("SHOW_TODOS", 0))
 gitstamp_fmt = "%d %b %Y"
 
 templates_path = ['_templates']

doc-source/requirements.txt

@@ -1,12 +1,12 @@
 autodocsumm
 extras_require
 pytz>=2019.1
+sphinx>=3.0.3
 sphinx-copybutton>=0.2.12
 sphinx-notfound-page
 sphinx-prompt>=1.2.0
 sphinx-tabs>=1.1.13
-sphinx>=3.0.3
 sphinx_autodoc_typehints>=1.11.0
-sphinx_rtd_theme<0.4
+sphinx_rtd_theme<0.5
 sphinxcontrib-httpdomain>=1.7.0
 sphinxemoji>=0.1.6

domdf_python_tools/paths.py

@@ -282,6 +282,8 @@ class PathPlus(pathlib.Path):
 	instantiating a Path will return either a PosixPath or a WindowsPath
 	object. You can also instantiate a PosixPath or WindowsPath directly,
 	but cannot instantiate a WindowsPath on a POSIX system or vice versa.
+
+	.. versionadded:: 0.3.8
 	"""
 
 	def __new__(cls, *args, **kwargs):
@@ -296,6 +298,8 @@ def __new__(cls, *args, **kwargs):
 	def make_executable(self):
 		"""
 		Make the file executable.
+
+		.. versionadded:: 0.3.8
 		"""
 
 		make_executable(self)
@@ -313,6 +317,8 @@ def write_clean(
 		:type string: str
 		:param encoding: The encoding to write to the file using. Default ``"UTF-8"``.
 		:param errors:
+
+		.. versionadded:: 0.3.8
 		"""
 
 		with self.open("w", encoding=encoding, errors=errors) as fp:
@@ -338,6 +344,8 @@ def maybe_make(
 			will be ignored (same behavior as the POSIX mkdir -p command), but only if the last path
 			component is not an existing non-directory file.
 		:type exist_ok: bool, optional
+
+		.. versionadded:: 0.3.8
 		"""
 
 		maybe_make(self, mode=mode, parents=parents, exist_ok=exist_ok)
@@ -355,6 +363,8 @@ def append_text(
 		:type string: str
 		:param encoding: The encoding to write to the file using. Default ``"UTF-8"``.
 		:param errors:
+
+		.. versionadded:: 0.3.8
 		"""
 
 		with self.open("a", encoding=encoding, errors=errors) as fp:
@@ -373,6 +383,8 @@ def write_text(
 		:type data: str
 		:param encoding: The encoding to write to the file using. Default ``"UTF-8"``.
 		:param errors:
+
+		.. versionadded:: 0.3.8
 		"""
 
 		return super().write_text(data, encoding=encoding, errors=errors)
@@ -389,6 +401,8 @@ def read_text(
 		:param errors:
 
 		:return: The content of the file.
+
+		.. versionadded:: 0.3.8
 		"""
 
 		return super().read_text(encoding=encoding, errors=errors)
@@ -404,6 +418,19 @@ def open(
 		"""
 		Open the file pointed by this path and return a file object, as
 		the built-in open() function does.
+
+		:param mode: The mode to open the file in. Default ``"r"`` (read only.
+		:type mode: str
+		:param buffering:
+		:type buffering: int
+		:param encoding:
+		:type encoding: str
+		:param errors:
+		:param newline:
+
+		:return:
+
+		.. versionadded:: 0.3.8
 		"""
 
 		if 'b' in mode:
@@ -415,6 +442,8 @@ class PosixPathPlus(PathPlus, pathlib.PurePosixPath):
 	"""Path subclass for non-Windows systems.
 
 	On a POSIX system, instantiating a PathPlus object should return an instance of this class.
+
+	.. versionadded:: 0.3.8
 	"""
 	__slots__ = ()
 
@@ -423,6 +452,8 @@ class WindowsPathPlus(PathPlus, pathlib.PureWindowsPath):
 	"""Path subclass for Windows systems.
 
 	On a Windows system, instantiating a PathPlus object should return an instance of this class.
+
+	.. versionadded:: 0.3.8
 	"""
 	__slots__ = ()
 

domdf_python_tools/terminal.py

@@ -76,7 +76,7 @@ def clear() -> None:
 	"""
 	Clears the display.
 
-	Works for Windows and UNIX, but does not clear Python Interpreter or PyCharm Console.
+	Works for Windows and POSIX, but does not clear the Python Interpreter or PyCharm's Console.
 	"""
 
 	if os.name == "nt":
@@ -106,17 +106,17 @@ def interrupt() -> None:
 
 def overtype(*objects, sep: str = ' ', end: str = '', file=sys.stdout, flush: bool = False) -> None:
 	"""
-	Print ``objects`` to the text stream ``file``, starting with "\\r", separated by ``sep``
+	Print ``objects`` to the text stream ``file``, starting with ``"\\r"``, separated by ``sep``
 	and followed by ``end``.
 
 	``sep``, ``end``, ``file`` and ``flush``, if present, must be given as keyword arguments
 
 	All non-keyword arguments are converted to strings like :class:`str` does and written to the stream,
 	separated by `sep` and followed by `end`.
 
-	If no objects are given, :func:`~domdf_python_tools.terminal.overtype` will just write "\\r".
+	If no objects are given, :func:`~domdf_python_tools.terminal.overtype` will just write ``"\\r"``.
 
-	TODO: This does not currently work in the PyCharm console, at least on Windows
+	.. TODO:: This does not currently work in the PyCharm console, at least on Windows
 
 	:param objects: A list of strings or string-like objects to write to the terminal.
 	:param sep: String to separate the objects with, by default " "

tox.ini

@@ -34,6 +34,7 @@ commands =
 
 
 [testenv:docs]
+setenv = SHOW_TODOS = 1
 basepython = python3.8
 changedir = {toxinidir}/doc-source
 deps =