Updating docstrings

domdfcoding · domdfcoding · commit e83e6a793f94 · 2020-04-29T22:53:12.000+01:00
diff --git a/.gitignore b/.gitignore
@@ -103,6 +103,36 @@ venv.bak/
 # mypy
 .mypy_cache/
 
+
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# Gradle
+*.iml
+*.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+
 .idea
 build
 *.egg-info
diff --git a/.travis.yml b/.travis.yml
@@ -20,4 +20,4 @@ deploy:
     tags: true
     python: "3.6"
   distributions: "sdist bdist_wheel"
-  skip_existing: true
+  skip_existing: true
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,2 +1,3 @@
 include __pkginfo__.py
 include LICENSE
+recursive-exclude **/__pycache__ *
diff --git a/__pkginfo__.py b/__pkginfo__.py
@@ -1,4 +1,4 @@
-# Copyright © 2020 Dominic Davis-Foster <dominic@davis-foster.co.uk>
+# Copyright (C) 2019-2020 Dominic Davis-Foster <dominic@davis-foster.co.uk>
 #
 #  This program is free software: you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by
@@ -18,7 +18,7 @@
 import pathlib
 
 copyright = """
-2019 Dominic Davis-Foster <dominic@davis-foster.co.uk>
+2019-2020 Dominic Davis-Foster <dominic@davis-foster.co.uk>
 """
 
 VERSION = "0.2.6"
@@ -31,22 +31,15 @@
 
 short_desc = 'Helpful functions for Python'
 
-classifiers = [
-		'Development Status :: 4 - Beta',
-		'Intended Audience :: Developers',
-		"License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
-		'Operating System :: OS Independent',
-		'Programming Language :: Python',
-		'Programming Language :: Python :: 3.6',
-		'Programming Language :: Python :: 3.7',
-		'Programming Language :: Python :: 3.8',
-		'Topic :: Software Development :: Libraries :: Python Modules',
-		]
-
 author = "Dominic Davis-Foster"
 author_email = "dominic@davis-foster.co.uk"
 github_username = "domdfcoding"
 web = github_url = f"https://github.com/{github_username}/{modname}"
+project_urls = {
+		"Documentation": f"https://{modname}.readthedocs.io",  # TODO: Make this link match the package version
+		"Issue Tracker": f"{github_url}/issues",
+		"Source Code": github_url,
+		}
 
 install_requires = []
 
@@ -55,3 +48,22 @@
 	long_description = (pathlib.Path.cwd().parent / "README.rst").read_text() + '\n'
 else:
 	long_description = pathlib.Path("README.rst").read_text() + '\n'
+
+
+classifiers = [
+		'Development Status :: 4 - Beta',
+		# "Development Status :: 4 - Beta",
+		# "Development Status :: 5 - Production/Stable",
+		# "Development Status :: 6 - Mature",
+		# "Development Status :: 7 - Inactive",
+		'Intended Audience :: Developers',
+		"License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
+		'Operating System :: OS Independent',
+		'Programming Language :: Python',
+		'Programming Language :: Python :: 3.6',
+		'Programming Language :: Python :: 3.7',
+		'Programming Language :: Python :: 3.8',
+		"Programming Language :: Python :: 3 :: Only",
+		"Programming Language :: Python :: Implementation :: CPython",
+		'Topic :: Software Development :: Libraries :: Python Modules',
+		]
diff --git a/doc-source/dates.rst b/doc-source/dates.rst
@@ -0,0 +1,14 @@
+*********************************
+:mod:`domdf_python_tools.dates`
+*********************************
+
+.. contents:: Table of Contents
+
+.. warning:: This module has not been fully tested. Use with caution.
+
+.. note:: This module requires the `pytz <https://pypi.org/project/pytz/>`_ package to be installed.
+
+.. automodule:: domdf_python_tools.dates
+	:members:
+	:undoc-members:
+
diff --git a/doc-source/docs.rst b/doc-source/docs.rst
diff --git a/doc-source/doctools.rst b/doc-source/doctools.rst
@@ -0,0 +1,10 @@
+**************************************
+:mod:`domdf_python_tools.doctools`
+**************************************
+
+.. contents:: Table of Contents
+
+.. automodule:: domdf_python_tools.doctools
+	:members:
+	:undoc-members:
+
diff --git a/doc-source/index.rst b/doc-source/index.rst
@@ -5,10 +5,20 @@ View the :ref:`Function Index <genindex>` or browse the `Source Code <_modules/i
 
 `Browse the GitHub Repository <https://github.com/domdfcoding/domdf_python_tools>`__
 
+.. toctree::
+   :hidden:
+
+   Home<self>
+
 .. toctree::
     :maxdepth: 3
     :caption: Documentation
 
-    docs
+    dates
+    doctools
+    pagesizes
+    paths
+    terminal
+    utils
     Source
     Building
diff --git a/doc-source/pagesizes.rst b/doc-source/pagesizes.rst
@@ -0,0 +1,10 @@
+************************************
+:mod:`domdf_python_tools.pagesizes`
+************************************
+
+.. contents:: Table of Contents
+
+.. automodule:: domdf_python_tools.pagesizes
+	:members:
+	:undoc-members:
+
diff --git a/doc-source/paths.rst b/doc-source/paths.rst
@@ -0,0 +1,10 @@
+**********************************
+:mod:`domdf_python_tools.paths`
+**********************************
+
+.. contents:: Table of Contents
+
+.. automodule:: domdf_python_tools.paths
+	:members:
+	:undoc-members:
+
diff --git a/doc-source/terminal.rst b/doc-source/terminal.rst
@@ -0,0 +1,10 @@
+***********************************
+:mod:`domdf_python_tools.terminal`
+***********************************
+
+.. contents:: Table of Contents
+
+.. automodule:: domdf_python_tools.terminal
+	:members:
+	:undoc-members:
+
diff --git a/doc-source/utils.rst b/doc-source/utils.rst
@@ -0,0 +1,10 @@
+*********************************
+:mod:`domdf_python_tools.utils`
+*********************************
+
+.. contents:: Table of Contents
+
+.. automodule:: domdf_python_tools.utils
+	:members:
+	:undoc-members:
+
diff --git a/domdf_python_tools/dates.py b/domdf_python_tools/dates.py
@@ -114,12 +114,14 @@ def set_timezone(obj, tzinfo):
 		"""
 		Sets the timezone / tzinfo of the given :class:`datetime.datetime` object.
 		This will not convert the time (i.e. the hours will stay the same).
-		Use :func:`python:datetime.datetime.astimezone` to accomplish that
+		Use :meth:`python:datetime.datetime.astimezone` to accomplish that.
+		
 		:param obj:
 		:type obj:
 		:param tzinfo: 
 		:type tzinfo: 
-		:return: 
+		
+		:return:
 		:rtype: 
 		"""
 		
@@ -177,10 +179,10 @@ def parse_month(month):
 		"""
 		Converts an integer or shorthand month into the full month name
 
-		:param month:
+		:param month: The month number or shorthand name
 		:type month: str or int
 
-		:return:
+		:return: The full name of the month
 		:rtype: str
 		"""
 		
diff --git a/domdf_python_tools/doctools.py b/domdf_python_tools/doctools.py
@@ -34,10 +34,10 @@ def deindent_string(string):
 	"""
 	Removes all indentation from the given string
 
-	:param string:
+	:param string: The string to deindent
 	:type string: str
 
-	:return:
+	:return: The string without indentation
 	:rtype: str
 	"""
 	
@@ -49,7 +49,7 @@ def deindent_string(string):
 # Functions that do the work
 def document_object_from_another(target, original):
 	"""
-	Sets the docstring of the `target` function to that of the `original` function.
+	Sets the docstring of the ``target`` function to that of the ``original`` function.
 
 	This may be useful for subclasses or wrappers that use the same arguments.
 
@@ -64,7 +64,7 @@ def document_object_from_another(target, original):
 
 def append_doctring_from_another(target, original):
 	"""
-	Sets the docstring of the `target` function to that of the `original` function.
+	Sets the docstring of the ``target`` function to that of the ``original`` function.
 
 	This may be useful for subclasses or wrappers that use the same arguments.
 
@@ -97,7 +97,7 @@ def make_sphinx_links(input_string, builtins_list=None):
 	:param input_string: The string to process
 	:type input_string: str
 	:param builtins_list: A list of builtins to make links for
-	:type builtins_list: list of str
+	:type builtins_list: [str]
 
 	:return: processed string with links
 	:rtype: str
@@ -117,7 +117,7 @@ def make_sphinx_links(input_string, builtins_list=None):
 # Decorators that call the above functions
 def is_documented_by(original):
 	"""
-	Sets the docstring of the `target` function to that of the `original` function.
+	Sets the docstring of the ``target`` function to that of the ``original`` function.
 
 	This may be useful for subclasses or wrappers that use the same arguments.
 	"""
@@ -131,7 +131,7 @@ def wrapper(target):
 
 def append_docstring_from(original):
 	"""
-	Appends the docstring from the `original` function to the `target` function.
+	Appends the docstring from the ``original`` function to the ``target`` function.
 
 	This may be useful for subclasses or wrappers that use the same arguments.
 
diff --git a/domdf_python_tools/pagesizes.py b/domdf_python_tools/pagesizes.py
diff --git a/domdf_python_tools/paths.py b/domdf_python_tools/paths.py
diff --git a/domdf_python_tools/terminal.py b/domdf_python_tools/terminal.py
diff --git a/domdf_python_tools/utils.py b/domdf_python_tools/utils.py
diff --git a/setup.py b/setup.py

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`include __pkginfo__.py`
`2`	`2`	`include LICENSE`
	`3`	`+recursive-exclude */__pycache__ `