Updated docs and linting.

Author: domdfcoding

.travis.yml

@@ -21,7 +21,7 @@ install:
   - pip install coveralls coverage_pyver_pragma
 
 script:
-  - tox
+  - tox -vv
 after_success:
   - coveralls
 

doc-source/api/pagesizes/classes.rst

@@ -4,3 +4,4 @@
 
 .. automodule:: domdf_python_tools.pagesizes.classes
 	:undoc-members:
+	:exclude-members: __slots__

doc-source/conf.py

@@ -15,6 +15,7 @@
 # User-configurable lines
 import domdf_python_tools
 domdf_python_tools.__docs = True
+overloads_location = "bottom"
 # End of user-configurable lines
 
 github_username = "domdfcoding"

domdf_python_tools/__init__.py

@@ -2,7 +2,7 @@
 #
 #  __init__.py
 """
-Helpful functions for Python 🐍 🛠️
+Helpful functions for Python 🐍 🛠️ .
 """
 #
 #  Copyright © 2018-2020 by Dominic Davis-Foster <dominic@davis-foster.co.uk>

domdf_python_tools/dates.py

@@ -56,12 +56,10 @@ def get_utc_offset(
 			) -> Optional[datetime.timedelta]:
 		"""
 		Returns the offset between UTC and the requested timezone on the given date.
-		If ``date`` is ``None`` then the current date is used.
+		If ``date`` is :py:obj:`None` then the current date is used.
 
 		:param tz: ``pytz.timezone`` or a string representing the timezone
 		:param date: The date to obtain the UTC offset for
-
-		:return:
 		"""
 
 		if date is None:
@@ -79,12 +77,10 @@ def get_utc_offset(
 	def get_timezone(tz: str, date: Optional[datetime.datetime] = None) -> Optional[datetime.tzinfo]:
 		"""
 		Returns a localized :class:`pytz.timezone` object for the given date.
-		If ``date`` is ``None`` then the current date is used.
+		If ``date`` is :py:obj:`None` then the current date is used.
 
 		:param tz: A string representing a pytz timezone
 		:param date: The date to obtain the timezone for
-
-		:return:
 		"""
 
 		if date is None:
@@ -113,7 +109,7 @@ def get_timezone(tz: str, date: Optional[datetime.datetime] = None) -> Optional[
 
 def current_tzinfo() -> Optional[datetime.tzinfo]:
 	"""
-	Returns a tzinfo object for the current timezone
+	Returns a tzinfo object for the current timezone.
 
 	:rtype: :class:`python:datetime.tzinfo`
 	"""

domdf_python_tools/doctools.py

@@ -134,8 +134,8 @@ def make_sphinx_links(input_string: str, builtins_list: Optional[Sequence[str]]
 	:param builtins_list: A list of builtins to make links for.
 	:default builtins_list: dir(:py:obj:`builtins`)
 
-	:return: processed string with links
-	"""
+	:return: Processed string with links.
+	"""  # noqa SXL001
 
 	if builtins_list is None:
 		builtins_list = dir(builtins)
@@ -199,7 +199,7 @@ def sphinxify_docstring() -> Callable:
 
 	Make sure to have ``'python': ('https://docs.python.org/3/', None),`` in the
 	``intersphinx_mapping`` dict of your ``conf.py`` file for Sphinx.
-	"""
+	"""  # noqa SXL001
 
 	def wrapper(target: F) -> F:
 		target_doc = target.__doc__

domdf_python_tools/import_tools.py

@@ -60,7 +60,7 @@ def discover(
 		match_func: Optional[Callable[[Any], bool]] = None,
 		) -> List[Type[Any]]:
 	"""
-	Returns a list of objects in the directory matched by match_func
+	Returns a list of objects in the directory matched by ``match_func``.
 
 	:param package: A Python package
 	:param match_func: Function taking an object and returning true if the object is to be included in the output.

domdf_python_tools/pagesizes/classes.py

@@ -59,20 +59,26 @@
 
 class BaseSize(namedtuple("__BaseSize", "width, height")):
 	"""
-	Base class namedtuple representing a page size, in point
-
-	:param width: The page width
-	:type width: |AnyNumber|
-	:param height: The page height
-	:type height: |AnyNumber|
+	Base class namedtuple representing a page size, in point.
 	"""
 
 	__slots__: List[str] = []
 	_unit: Unit = pt
+
+	#: The page width.
 	width: Unit
+
+	#: The page height.
 	height: Unit
 
 	def __new__(cls, width: AnyNumber, height: AnyNumber):
+		"""
+		Create a new :class:`~.BaseSize` object.
+
+		:param width: The page width.
+		:param height: The page height.
+		"""
+
 		return super().__new__(
 				cls,
 				cls._unit(width),
@@ -88,10 +94,10 @@ def from_pt(cls, size: Tuple[float, float]):
 		Create a :class:`~domdf_python_tools.pagesizes.classes.BaseSize` object from a
 		page size in point.
 
-		:param size: The size, in point, to convert from
+		:param size: The size, in point, to convert from.
 
 		:rtype: A subclass of :class:`~domdf_python_tools.pagesizes.classes.BaseSize`
-		"""
+		"""  # noqa D400
 
 		assert isinstance(size, PageSize)
 
@@ -100,35 +106,35 @@ def from_pt(cls, size: Tuple[float, float]):
 	@classmethod
 	def from_size(cls, size: Tuple[AnyNumber, AnyNumber]) -> "BaseSize":
 		"""
-		Create a :class:`~domdf_python_tools.pagesizes.classes.BaseSize` object from a tuple
+		Create a :class:`~domdf_python_tools.pagesizes.classes.BaseSize` object from a tuple.
 		"""
 
 		return cls(*size)
 
 	def is_landscape(self) -> bool:
 		"""
-		Returns whether the page is in the landscape orientation
+		Returns whether the page is in the landscape orientation.
 		"""
 
 		return self.width >= self.height
 
 	def is_portrait(self) -> bool:
 		"""
-		Returns whether the page is in the portrait orientation
+		Returns whether the page is in the portrait orientation.
 		"""
 
 		return self.width < self.height
 
 	def is_square(self) -> bool:
 		"""
-		Returns whether the given pagesize is square
+		Returns whether the given pagesize is square.
 		"""
 
 		return self.width == self.height
 
 	def landscape(self) -> "BaseSize":
 		"""
-		Returns the pagesize in landscape orientation
+		Returns the pagesize in landscape orientation.
 		"""
 
 		if self.is_portrait():
@@ -138,7 +144,7 @@ def landscape(self) -> "BaseSize":
 
 	def portrait(self) -> "BaseSize":
 		"""
-		Returns the pagesize in portrait orientation
+		Returns the pagesize in portrait orientation.
 		"""
 
 		if self.is_landscape():
@@ -148,7 +154,7 @@ def portrait(self) -> "BaseSize":
 
 	def to_pt(self) -> "PageSize":
 		"""
-		Returns the page size in point
+		Returns the page size in point.
 		"""
 
 		return PageSize(self.width.as_pt(), self.height.as_pt())
@@ -159,83 +165,50 @@ def to_pt(self) -> "PageSize":
 
 class Size_mm(BaseSize):
 	"""
-	Subclass of :class:`~domdf_python_tools.pagesizes.classes.BaseSize`
-	representing a pagesize in millimeters.
-
-	:param width: The page width
-	:type width: |AnyNumber|
-	:param height: The page height
-	:type height: |AnyNumber|
+	Represents a pagesize in millimeters.
 	"""
 
 	_unit = mm
 
 
 class Size_inch(BaseSize):
 	"""
-	Subclass of :class:`~domdf_python_tools.pagesizes.classes.BaseSize`
-	representing a pagesize in inches.
-
-	:param width: The page width
-	:type width: |AnyNumber|
-	:param height: The page height
-	:type height: |AnyNumber|
+	Represents a pagesize in inches.
 	"""
 
 	_unit = inch
 
 
 class Size_cm(BaseSize):
 	"""
-	Subclass of :class:`~domdf_python_tools.pagesizes.classes.BaseSize`
-	representing a pagesize in centimeters.
-
-	:param width: The page width
-	:type width: |AnyNumber|
-	:param height: The page height
-	:type height: |AnyNumber|
+	Represents a pagesize in centimeters.
 	"""
 
 	_unit = cm
 
 
 class Size_um(BaseSize):
 	"""
-	Subclass of :class:`~domdf_python_tools.pagesizes.classes.BaseSize`
-	representing a pagesize in micrometers.
-
-	:param width: The page width
-	:type width: |AnyNumber|
-	:param height: The page height
-	:type height: |AnyNumber|
+	Represents a pagesize in micrometers.
 	"""
 
 	_unit = um
 
 
 class Size_pica(BaseSize):
 	"""
-	Subclass of :class:`~domdf_python_tools.pagesizes.classes.BaseSize`
-	representing a pagesize in pica.
-
-	:param width: The page width
-	:type width: |AnyNumber|
-	:param height: The page height
-	:type height: |AnyNumber|
+	Represents a pagesize in pica.
 	"""
 
 	_unit = pica
 
 
 class PageSize(BaseSize):
 	"""
-	Subclass of :class:`~domdf_python_tools.pagesizes.classes.BaseSize`
-	representing a pagesize in point.
+	Represents a pagesize in point.
 
 	:param width: The page width
-	:type width: |AnyNumber|
 	:param height: The page height
-	:type height: |AnyNumber|
 
 	The pagesize can be converted to other units using the properties below.
 	"""
@@ -246,8 +219,8 @@ def __new__(cls, width: AnyNumber, height: AnyNumber, unit: AnyNumber = pt):
 		"""
 		Create a new :class:`~domdf_python_tools.pagesizes.classes.PageSize` object.
 
-		:param width:
-		:param height:
+		:param width: The page width.
+		:param height: The page height.
 		:param unit:
 		"""
 

domdf_python_tools/pagesizes/sizes.py

@@ -2,7 +2,7 @@
 #
 #  sizes.py
 """
-Common pagesizes in point/pt
+Common pagesizes in point/pt.
 
 .. TODO:: finish the list of the page sizes
 

domdf_python_tools/pagesizes/utils.py

@@ -62,13 +62,11 @@ def convert_from(
 		value: Union[Sequence[AnyNumber], AnyNumber],
 		from_: AnyNumber,
 		) -> Union[float, Tuple[float, ...]]:
-	"""
+	r"""
 	Convert ``value`` to point from the unit specified in ``from_``.
 
 	:param value:
-	:param from_: The unit to convert from, specified as a number of points
-
-	:return:
+	:param from\_: The unit to convert from, specified as a number of points.
 	"""
 
 	if isinstance(value, Sequence):
@@ -94,9 +92,6 @@ def parse_measurement(measurement: str) -> Union[float, Tuple[float, ...]]:
 	Parse the given measurement.
 
 	:param measurement:
-	:type measurement: str
-
-	:return:
 	"""
 
 	# TODO: docstring
@@ -109,7 +104,7 @@ def parse_measurement(measurement: str) -> Union[float, Tuple[float, ...]]:
 
 	val, unit = all_matches[0]
 
-	if "" in {val, unit}:
+	if '' in {val, unit}:
 		raise ValueError("Unable to parse measurement")
 
 	val = float(val)