Updated docs.

domdfcoding · domdfcoding · commit c91a36662031 · 2020-08-11T09:39:40.000+01:00
diff --git a/doc-source/api/bases.rst b/doc-source/api/bases.rst
@@ -3,8 +3,5 @@
 *********************************
 
 .. automodule:: domdf_python_tools.bases
-	:autosummary:
-	:members:
 	:inherited-members:
 	:special-members:
-	:exclude-members: __dir__, __dict__, __subclasshook__, __init_subclass__, __init__, __weakref__
diff --git a/doc-source/api/dates.rst b/doc-source/api/dates.rst
@@ -11,6 +11,27 @@
 
 
 .. automodule:: domdf_python_tools.dates
-	:autosummary:
-	:members:
 	:undoc-members:
+
+	.. py:data:: months
+
+		Mapping of months to their 3-character shortcodes.
+
+		Essentially:
+
+		.. code-block:: python
+
+			months = {
+				Jan="January",
+				Feb="February",
+				Mar="March",
+				Apr="April",
+				May="May",
+				Jun="June",
+				Jul="July",
+				Aug="August",
+				Sep="September",
+				Oct="October",
+				Nov="November",
+				Dec="December",
+			}
diff --git a/doc-source/api/doctools.rst b/doc-source/api/doctools.rst
@@ -3,6 +3,4 @@
 **************************************
 
 .. automodule:: domdf_python_tools.doctools
-	:autosummary:
-	:members:
 	:undoc-members:
diff --git a/doc-source/api/import_tools.rst b/doc-source/api/import_tools.rst
@@ -3,6 +3,4 @@
 **************************************
 
 .. automodule:: domdf_python_tools.import_tools
-	:autosummary:
-	:members:
 	:undoc-members:
diff --git a/doc-source/api/pagesizes.rst b/doc-source/api/pagesizes.rst
diff --git a/doc-source/api/pagesizes/classes.rst b/doc-source/api/pagesizes/classes.rst
@@ -0,0 +1,6 @@
+============================================
+:mod:`domdf_python_tools.pagesizes.classes`
+============================================
+
+.. automodule:: domdf_python_tools.pagesizes.classes
+	:undoc-members:
diff --git a/doc-source/api/pagesizes/index.rst b/doc-source/api/pagesizes/index.rst
@@ -0,0 +1,12 @@
+=========================================
+:mod:`domdf_python_tools.pagesizes`
+=========================================
+
+.. toctree::
+	:caption: Submodules
+	:glob:
+
+	*
+
+.. automodule:: domdf_python_tools.pagesizes
+	:undoc-members:
diff --git a/doc-source/api/pagesizes/sizes.rst b/doc-source/api/pagesizes/sizes.rst
@@ -0,0 +1,8 @@
+=========================================
+:mod:`domdf_python_tools.pagesizes.sizes`
+=========================================
+
+.. automodule:: domdf_python_tools.pagesizes.sizes
+	:undoc-members:
+	:special-members:
+	:private-members:
diff --git a/doc-source/api/pagesizes/units.rst b/doc-source/api/pagesizes/units.rst
@@ -0,0 +1,6 @@
+=========================================
+:mod:`domdf_python_tools.pagesizes.units`
+=========================================
+
+.. automodule:: domdf_python_tools.pagesizes.units
+	:undoc-members:
diff --git a/doc-source/api/pagesizes/utils.rst b/doc-source/api/pagesizes/utils.rst
@@ -0,0 +1,6 @@
+=========================================
+:mod:`domdf_python_tools.pagesizes.utils`
+=========================================
+
+.. automodule:: domdf_python_tools.pagesizes.utils
+	:undoc-members:
diff --git a/doc-source/api/paths.rst b/doc-source/api/paths.rst
@@ -3,6 +3,4 @@
 **********************************
 
 .. automodule:: domdf_python_tools.paths
-	:members:
-	:autosummary:
 	:undoc-members:
diff --git a/doc-source/api/secrets.rst b/doc-source/api/secrets.rst
@@ -3,7 +3,4 @@
 *********************************
 
 .. automodule:: domdf_python_tools.secrets
-	:members:
-	:autosummary:
 	:special-members:
-	:exclude-members: __dir__, __weakref__
diff --git a/doc-source/api/terminal.rst b/doc-source/api/terminal.rst
@@ -3,8 +3,5 @@
 ***********************************
 
 .. automodule:: domdf_python_tools.terminal
-	:members:
-	:autosummary:
 	:undoc-members:
 	:special-members:
-	:exclude-members: __dir__
diff --git a/doc-source/api/terminal_colours.rst b/doc-source/api/terminal_colours.rst
@@ -3,5 +3,3 @@
 *******************************************
 
 .. automodule:: domdf_python_tools.terminal_colours
-	:members:
-	:autosummary:
diff --git a/doc-source/api/typing.rst b/doc-source/api/typing.rst
@@ -3,6 +3,4 @@
 ***********************************
 
 .. automodule:: domdf_python_tools.typing
-	:members:
-	:autosummary:
 	:undoc-members:
diff --git a/doc-source/api/utils.rst b/doc-source/api/utils.rst
@@ -3,6 +3,4 @@
 *********************************
 
 .. automodule:: domdf_python_tools.utils
-	:members:
-	:autosummary:
 	:undoc-members:
diff --git a/doc-source/api/versions.rst b/doc-source/api/versions.rst
@@ -3,8 +3,5 @@
 ************************************
 
 .. automodule:: domdf_python_tools.versions
-	:members:
-	:autosummary:
 	:undoc-members:
 	:special-members:
-	:exclude-members: __dir__
diff --git a/doc-source/api/words.rst b/doc-source/api/words.rst
@@ -3,5 +3,3 @@
 *********************************
 
 .. automodule:: domdf_python_tools.words
-	:members:
-	:autosummary:
diff --git a/doc-source/conf.py b/doc-source/conf.py
@@ -104,6 +104,24 @@
 texinfo_documents = [('index', slug, project, author, slug, project, 'Miscellaneous')]
 
 
+autodoc_default_options = {
+		'members': None,  # Include all members (methods).
+		'special-members': None,
+		"autosummary": None,
+		'exclude-members': ','.join([   # Exclude "standard" methods.
+				"__dict__",
+				"__dir__",
+				"__weakref__",
+				"__module__",
+				"__annotations__",
+				"__orig_bases__",
+				"__parameters__",
+				"__subclasshook__",
+				"__init_subclass__",
+				])
+		}
+
+
 # Extensions to theme docs
 def setup(app):
 	from sphinx.domains.python import PyField
diff --git a/doc-source/index.rst b/doc-source/index.rst
@@ -160,6 +160,7 @@ Installation
 	:glob:
 
 	api/*
+	api/*/index
 
 .. toctree::
 	:maxdepth: 3
diff --git a/domdf_python_tools/dates.py b/domdf_python_tools/dates.py
@@ -49,7 +49,6 @@ def get_utc_offset(
 		If ``date`` is ``None`` then the current date is used.
 
 		:param tz: ``pytz.timezone`` or a string representing the timezone
-		:type tz:
 		:param date: The date to obtain the UTC offset for
 
 		:return:
@@ -73,9 +72,7 @@ def get_timezone(tz: str, date: Optional[datetime.datetime] = None) -> Optional[
 		If ``date`` is ``None`` then the current date is used.
 
 		:param tz: A string representing a pytz timezone
-		:type tz: str
 		:param date: The date to obtain the timezone for
-		:type date: datetime.datetime, optional
 
 		:return:
 		"""
@@ -94,7 +91,9 @@ def get_timezone(tz: str, date: Optional[datetime.datetime] = None) -> Optional[
 
 	warnings.warn(
 			f"""\
-Some functions in 'domdf_python_tools.dates' require pytz (https://pypi.org/project/pytz/), but it could not be imported.
+Some functions in 'domdf_python_tools.dates' require pytz (https://pypi.org/project/pytz/), \
+but it could not be imported.
+
 The error was {e}.
 """,
 			)
@@ -159,13 +158,10 @@ def utc_timestamp_to_datetime(
 
 
 	:param utc_timestamp: The timestamp to convert to a datetime object
-	:type utc_timestamp: float, int
 	:param output_tz: The timezone to output the datetime object for.
-		If None it will be inferred.
-	:type output_tz: datetime.tzinfo, optional
+		If :py:obj:`None` it will be inferred.
 
 	:return: The timestamp as a datetime object.
-	:rtype: datetime.datetime
 
 	:raises: :class:`~python:OverflowError` if the timestamp is out of the range
 		of values supported by the platform C localtime() or gmtime() functions,
@@ -177,7 +173,7 @@ def utc_timestamp_to_datetime(
 	return new_datetime.astimezone(output_tz)
 
 
-# List of months and their 3-character shortcodes.
+# Mapping of months to their 3-character shortcodes.
 months = OrderedDict(
 		Jan="January",
 		Feb="February",
@@ -199,7 +195,6 @@ def parse_month(month: Union[str, int]) -> str:
 	Converts an integer or shorthand month into the full month name.
 
 	:param month: The month number or shorthand name
-	:type month: str or int
 
 	:return: The full name of the month
 	"""
@@ -225,10 +220,8 @@ def get_month_number(month: Union[str, int]) -> int:
 	If ``month`` is already a number between 1 and 12 it will be returned immediately.
 
 	:param month: The month to convert to a number
-	:type month: str or int
 
 	:return: The number of the month
-	:rtype: int
 	"""
 
 	if isinstance(month, int):
@@ -248,14 +241,10 @@ def check_date(month: Union[str, int], day: int, leap_year: bool = True) -> bool
 	want this behaviour set ``leap_year`` to :py:obj:`False`.
 
 	:param month: The month to test.
-	:type month: str, int
 	:param day: The day number to test.
-	:type day: int
 	:param leap_year: Whether to return :py:obj:`True` for 29th Feb.
-	:type leap_year: bool, optional
 
 	:return: :py:obj:`True` if the date is valid.
-	:rtype: bool
 	"""
 
 	# Ensure day is an integer
diff --git a/domdf_python_tools/doctools.py b/domdf_python_tools/doctools.py
@@ -97,14 +97,24 @@ def make_sphinx_links(input_string: str, builtins_list: Optional[Sequence[str]]
 	r"""
 	Make proper sphinx links out of double-backticked strings in docstring.
 
-	i.e. \`\`str\`\` becomes \:class\:\`~python:str\`
+	i.e.
 
+	.. code-block:: rest
 
-	Make sure to have `'python': ('https://docs.python.org/3/', None),` in the
-	`intersphinx_mapping` dict of your conf.py for sphinx.
+		``str``
 
-	:param input_string: The string to process
-	:param builtins_list: A list of builtins to make links for
+	becomes
+
+	.. code-block:: rest
+
+		:class:`~python:str`
+
+	Make sure to have ``'python': ('https://docs.python.org/3/', None),`` in the
+	``intersphinx_mapping`` dict of your ``conf.py`` file for Sphinx.
+
+	:param input_string: The string to process.
+	:param builtins_list: A list of builtins to make links for.
+	:default builtins_list: dir(:py:obj:`builtins`)
 
 	:return: processed string with links
 	"""
@@ -157,7 +167,17 @@ def sphinxify_docstring() -> Callable:
 	r"""
 	Decorator to make proper sphinx links out of double-backticked strings in the docstring.
 
-	i.e. \`\`str\`\` becomes \:class\:\`~python:str\`
+	i.e.
+
+	.. code-block:: rest
+
+		``str``
+
+	becomes
+
+	.. code-block:: rest
+
+		:class:`~python:str`
 
 	Make sure to have ``'python': ('https://docs.python.org/3/', None),`` in the
 	``intersphinx_mapping`` dict of your ``conf.py`` file for Sphinx.
diff --git a/domdf_python_tools/pagesizes/__init__.py b/domdf_python_tools/pagesizes/__init__.py
@@ -28,7 +28,7 @@
 #
 #  This program is distributed in the hope that it will be useful,
 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 #  GNU Lesser General Public License for more details.
 #
 #  You should have received a copy of the GNU Lesser General Public License
diff --git a/domdf_python_tools/pagesizes/_types.py b/domdf_python_tools/pagesizes/_types.py
diff --git a/domdf_python_tools/pagesizes/classes.py b/domdf_python_tools/pagesizes/classes.py
diff --git a/domdf_python_tools/pagesizes/sizes.py b/domdf_python_tools/pagesizes/sizes.py
diff --git a/domdf_python_tools/pagesizes/units.py b/domdf_python_tools/pagesizes/units.py
diff --git a/domdf_python_tools/pagesizes/utils.py b/domdf_python_tools/pagesizes/utils.py
diff --git a/domdf_python_tools/secrets.py b/domdf_python_tools/secrets.py
diff --git a/domdf_python_tools/typing.py b/domdf_python_tools/typing.py
diff --git a/domdf_python_tools/versions.py b/domdf_python_tools/versions.py
diff --git a/domdf_python_tools/words.py b/domdf_python_tools/words.py
