Tidying up code and added new functions (doctools.py) to aid in documenting functions, classes and methods

Author: domdfcoding

doc-source/docs.rst

@@ -9,6 +9,16 @@
     :private-members:
     :special-members:
 
+==================================
+:mod:`domdf_python_tools.doctools`
+==================================
+
+
+.. automodule:: domdf_python_tools.doctools
+    :members:
+    :private-members:
+    :special-members:
+
 ==================================
 :mod:`domdf_python_tools.paths`
 ==================================

domdf_python_tools/__init__.py

@@ -1,22 +1,26 @@
 #  Compiled 2018-2019 by Dominic Davis-Foster <dominic@davis-foster.co.uk>
-
-
 #
 #  terminal.py
 #  		Copyright 2014-2019 Dominic Davis-Foster <dominic@davis-foster.co.uk>
 #
 #  		get_terminal_size, _get_terminal_size_windows, _get_terminal_size_tput and _get_terminal_size_linux
-#			from https://gist.github.com/jtriley/1108174
+# 			from https://gist.github.com/jtriley/1108174
 #  			Copyright 2011 jtriley
 #
 #  paths.py
-#		Copyright 2018-2019 Dominic Davis-Foster <dominic@davis-foster.co.uk>
+# 		Copyright 2018-2019 Dominic Davis-Foster <dominic@davis-foster.co.uk>
 #
 #  		copytree based on https://stackoverflow.com/a/12514470/3092681
-#			Copyright 2012 atzz
-#			Licensed under CC-BY-SA
+# 			Copyright 2012 atzz
+# 			Licensed under CC-BY-SA
 #
 
+
+import sys
+
+from domdf_python_tools.utils import *
+from domdf_python_tools import paths, terminal, utils, doctools
+
 __all__ = ["paths", "terminal", "utils"]
 
 __author__ = "Dominic Davis-Foster"
@@ -27,11 +31,4 @@
 __email__ = "dominic@davis-foster.co.uk"
 
 
-import sys
-
-from . import paths
-from . import terminal
-from . import utils
-from domdf_python_tools.utils import *
-
 pyversion = int(sys.version[0])  # Python Version

domdf_python_tools/doctools.py

@@ -0,0 +1,41 @@
+#  !/usr/bin/env python
+#   -*- coding: utf-8 -*-
+#
+#  doctools.py
+"""
+Utilities for documenting functions, classes and methods
+"""
+#
+#  Based on https://softwareengineering.stackexchange.com/a/386758
+#  Copyright (c) amon (https://softwareengineering.stackexchange.com/users/60357/amon)
+#  Licensed under CC BY-SA 4.0
+#
+#  This program is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  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
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program; if not, write to the Free Software
+#  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+#  MA 02110-1301, USA.
+#
+
+
+def is_documented_by(original):
+	def wrapper(target):
+		target.__doc__ = original.__doc__
+		return target
+	return wrapper
+
+
+def append_docstring_from(original):
+	def wrapper(target):
+		target.__doc__ = target.__doc__ + "\n" + original.__doc__
+		return target
+	return wrapper

domdf_python_tools/paths.py

@@ -2,22 +2,23 @@
 # -*- coding: utf-8 -*-
 #
 #  paths.py
-"""Functions for paths and files"""
+"""
+Functions for paths and files
+"""
 #
 #  Copyright 2018-2019 Dominic Davis-Foster <dominic@davis-foster.co.uk>
 #
 #  check_dependencies based on https://stackoverflow.com/a/29044693/3092681
 #  		Copyright 2015 TehTechGuy
-#		Licensed under CC-BY-SA
+# 		Licensed under CC-BY-SA
 #
 #  as_text from https://stackoverflow.com/a/40935194
-#		Copyright 2016 User3759685
-#		Available under the MIT License
+# 		Copyright 2016 User3759685
+# 		Available under the MIT License
 #
 #  chunks from https://stackoverflow.com/a/312464/3092681
-#		Copytight 2008 Ned Batchelder
-#		Licensed under CC-BY-SA
-#
+# 		Copytight 2008 Ned Batchelder
+# 		Licensed under CC-BY-SA
 #
 #  This program is free software; you can redistribute it and/or modify
 #  it under the terms of the GNU Lesser General Public License as published by
@@ -39,6 +40,7 @@
 import os
 import pathlib
 
+
 def copytree(src, dst, symlinks=False, ignore=None):
 	"""
 	Because shutil.copytree is borked
@@ -70,6 +72,7 @@ def copytree(src, dst, symlinks=False, ignore=None):
 		else:
 			return shutil.copy2(s, d)
 
+
 def maybe_make(directory):
 	"""
 	Makes a directory only if it doesn't already exist
@@ -82,6 +85,7 @@ def maybe_make(directory):
 	if not os.path.exists(directory):
 		os.makedirs(directory)
 
+
 def parent_path(path):
 	"""
 	Returns the path of the parent directory for the given file or directory
@@ -94,6 +98,7 @@ def parent_path(path):
 
 	return os.path.abspath(os.path.join(path,os.pardir))
 
+
 def relpath(path, relative_to=None):
 	"""
 	Returns the path for the given file or directory relative to the given directory
@@ -209,4 +214,3 @@ def append(var, filename):
 
 	with open(os.path.join(os.getcwd(), filename), 'a') as f:
 		f.write(var)
-

domdf_python_tools/terminal.py

@@ -2,12 +2,14 @@
 # -*- coding: utf-8 -*-
 #
 #  terminal.py
-"""Useful functions for terminal-based programs"""
+"""
+Useful functions for terminal-based programs
+"""
 #
 #  Copyright 2014-2019 Dominic Davis-Foster <dominic@davis-foster.co.uk>
 #
 #  get_terminal_size, _get_terminal_size_windows, _get_terminal_size_tput and _get_terminal_size_linux
-#		from https://gist.github.com/jtriley/1108174
+# 		from https://gist.github.com/jtriley/1108174
 #  		Copyright 2011 jtriley
 #
 #  This program is free software; you can redistribute it and/or modify
@@ -27,13 +29,16 @@
 #
 #
 
+# stdlib
 import os
 import sys
 import shlex
 import struct
 import platform
 import subprocess
-from .__init__ import pyversion
+
+# this package
+from domdf_python_tools import pyversion
 
 
 def clear():
@@ -55,6 +60,7 @@ def br():
 
 	print("")
 
+
 def entry(text_to_print):
 	"""
 	Version-agnostic input function
@@ -195,6 +201,7 @@ def ioctl_GWINSZ(fd):
 			return None
 	return int(cr[1]), int(cr[0])
 
+
 if __name__ == "__main__":
 	sizex, sizey = get_terminal_size()
 	print('width =', sizex, 'height =', sizey)

domdf_python_tools/utils.py

@@ -2,7 +2,9 @@
 # -*- coding: utf-8 -*-
 #
 #  utils.py
-"""General Functions"""
+"""
+General Functions
+"""
 #
 #  Copyright 2018-2019 Dominic Davis-Foster <dominic@davis-foster.co.uk>
 #