Even more documentation of the internal modules

docs/conf.py

@@ -31,7 +31,7 @@ year_current = date.today().year
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.todo', 'sphinx.ext.autodoc', 'sphinxcontrib.httpdomain', 'sphinx.ext.autosummary', 'sphinxcontrib.napoleon']
+extensions = ['sphinx.ext.todo', 'sphinx.ext.autodoc', 'sphinxcontrib.httpdomain', 'sphinxcontrib.napoleon']
 todo_include_todos = True
 
 # Add any paths that contain templates here, relative to this directory.

docs/development/index.rst

@@ -4,7 +4,7 @@
 Development
 ###########
 
-.. toctree::
+.. todo::
-   :maxdepth: 3
 
-   interface/index.rst
+   This is where notes regarding developing OctoPrint will be placed, such as workflow for setting up the
+   development environment, code guidelines etc.

docs/development/interface/printer.rst

@@ -1,8 +0,0 @@
-.. _sec-development-interface-printer:
-
-octoprint.printer
------------------
-
-.. automodule:: octoprint.printer
-   :members: Printer
-   :undoc-members:

docs/index.rst

@@ -19,5 +19,5 @@ Contents
    api/index.rst
    events/index.rst
    plugins/index.rst
-   development/index.rst
+   modules/index.rst
 

docs/modules/filemanager.rst

@@ -1,31 +1,28 @@
-.. _sec-development-interface-filemanager:
+.. _sec-modules-filemanager:
 
 octoprint.filemanager
 ---------------------
 
 .. automodule:: octoprint.filemanager
    :members:
-   :undoc-members:
 
-.. _sec-development-interface-filemanager-analysis:
+.. _sec-modules-filemanager-analysis:
 
 octoprint.filemanager.analysis
 ------------------------------
 
 .. automodule:: octoprint.filemanager.analysis
    :members:
-   :undoc-members:
 
-.. _sec-development-interface-filemanager-destinations:
+.. _sec-modules-filemanager-destinations:
 
 octoprint.filemanager.destinations
 ----------------------------------
 
 .. automodule:: octoprint.filemanager.destinations
    :members:
-   :undoc-members:
 
-.. _sec-development-interface-filemanager-storage:
+.. _sec-modules-filemanager-storage:
 
 octoprint.filemanager.storage
 -----------------------------

docs/modules/index.rst

@@ -1,7 +1,8 @@
-.. _sec-development-interface:
+.. _sec-modules:
 
-Internal API
+################
-============
+Internal Modules
+################
 
 .. toctree::
    :maxdepth: 3
@@ -9,4 +10,5 @@ Internal API
    filemanager.rst
    plugin.rst
    printer.rst
+   settings.rst
    util.rst

docs/modules/plugin.rst

@@ -1,19 +1,20 @@
-.. _sec-development-interface-plugin:
+.. _sec-modules-plugin:
 
 octoprint.plugin
 ----------------
 
 .. automodule:: octoprint.plugin
 
-.. _sec-development-interface-plugin-core:
+.. _sec-modules-plugin-core:
 
 octoprint.plugin.core
 ---------------------
 
 .. automodule:: octoprint.plugin.core
 
+.. _sec-modules-plugin-types:
+
 octoprint.plugin.types
 ----------------------
 
 .. automodule:: octoprint.plugin.types
-

docs/modules/printer.rst

@@ -0,0 +1,6 @@
+.. _sec-modules-printer:
+
+octoprint.printer
+-----------------
+
+.. automodule:: octoprint.printer

docs/modules/settings.rst

@@ -0,0 +1,6 @@
+.. _sec-modules-settings:
+
+octoprint.settings
+------------------
+
+.. automodule:: octoprint.settings

docs/modules/util.rst

@@ -1,4 +1,4 @@
-.. _sec-development-interface-util:
+.. _sec-modules-util:
 
 octoprint.util
 --------------

docs/plugins/index.rst

@@ -1,5 +1,3 @@
-.. automodule:: octoprint.plugin.types
-
 .. _sec-plugins:
 
 #######

docs/plugins/mixins.rst

@@ -9,7 +9,7 @@ The following plugin mixins are currently available:
    :local:
 
 Please note that all plugin mixins inherit from :class:`~octoprint.plugin.core.Plugin` and
-:class:`~octoprint.plugin.OctoPrintPlugin`, which also provide attributes of interest to plugin developers.
+:class:`~octoprint.plugin.types.OctoPrintPlugin`,  which also provide attributes of interest to plugin developers.
 
 .. _sec-plugins-mixins-startupplugin:
 

src/octoprint/plugin/__init__.py

@@ -11,7 +11,6 @@ registered plugin types.
 
 .. autoclass:: PluginSettings
    :members:
-
 """
 
 from __future__ import absolute_import
@@ -63,11 +62,12 @@ def plugin_manager(init=False, plugin_folders=None, plugin_types=None, plugin_en
 	"""
 
 	global _instance
-	if _instance is None:
+	if _instance is not None:
 		if init:
-			if _instance is not None:
+			raise ValueError("Plugin Manager already initialized")
-				raise ValueError("Plugin Manager already initialized")
 
+	else:
+		if init:
 			if plugin_folders is None:
 				plugin_folders = (settings().getBaseFolder("plugins"), os.path.abspath(os.path.join(os.path.dirname(os.path.realpath(__file__)), "..", "plugins")))
 			if plugin_types is None:
@@ -178,40 +178,63 @@ class PluginSettings(object):
 	It provides a couple of convenience methods for directly accessing plugin settings via the regular
 	:class:`octoprint.settings.Settings` interfaces as well as means to access plugin specific folder locations.
 
+	All getter and setter methods will ensure that plugin settings are stored in their correct location within the
+	settings structure by modifying the supplied paths accordingly.
+
+	Arguments:
+	    settings (Settings): The :class:`~octoprint.settings.Settings` instance on which to operate.
+	    plugin_key (str): The plugin identifer of the plugin for which to create this instance.
+	    defaults (dict): The plugin's defaults settings, will be used to determine valid paths within the plugin's
+	        settings structure
+
 	.. method:: get(path, merged=False, asdict=False)
 
-	   Retrieves a raw key from the settings for ``path``, optionally merging the raw value with the default settings
+	   Retrieves a raw value from the settings for ``path``, optionally merging the raw value with the default settings
 	   if ``merged`` is set to True.
 
-	   :param list path:      a list of path elements to navigate to the settings value
+	   :param path: The path for which to retrieve the value.
-	   :param boolean merged: whether to merge the returned result with the default settings (True) or not (False, default)
+	   :type path: list, tuple
-	   :return: the retrieved settings value
+	   :param boolean merged: Whether to merge the returned result with the default settings (True) or not (False,
+	       default).
+	   :returns: The retrieved settings value.
+	   :rtype: object
 
 	.. method:: get_int(path)
 
+	   Like :func:`get` but tries to convert the retrieved value to ``int``.
+
 	.. method:: get_float(path)
 
+	   Like :func:`get` but tries to convert the retrieved value to ``float``.
+
 	.. method:: get_boolean(path)
 
+	   Like :func:`get` but tries to convert the retrieved value to ``boolean``.
+
 	.. method:: set(path, value, force=False)
 
+	   Sets the raw value on the settings for ``path``.
+
+	   :param path: The path for which to retrieve the value.
+	   :type path: list, tuple
+	   :param object value: The value to set.
+	   :param boolean force: If set to True, the modified configuration will even be written back to disk if
+	       the value didn't change.
+
 	.. method:: set_int(path, value, force=False)
 
+	   Like :func:`set` but ensures the value is an ``int`` through attempted conversion before setting it.
+
 	.. method:: set_float(path, value, force=False)
 
+	   Like :func:`set` but ensures the value is an ``float`` through attempted conversion before setting it.
+
 	.. method:: set_boolean(path, value, force=False)
+
+	   Like :func:`set` but ensures the value is an ``boolean`` through attempted conversion before setting it.
 	"""
 
 	def __init__(self, settings, plugin_key, defaults=None):
-		"""
-		Initializes the object with the provided :class:`octoprint.settings.Settings` manager as ``settings``, using
-		the ``plugin_key`` and optional ``defaults``.
-
-		:param settings:
-		:param plugin_key:
-		:param defaults:
-		:return:
-		"""
 		self.settings = settings
 		self.plugin_key = plugin_key
 
@@ -253,33 +276,83 @@ class PluginSettings(object):
 		self.deprecated_access_methods = dict(getInt="get_int", getFloat="get_float", getBoolean="get_boolean", setInt="set_int", setFloat="set_float", setBoolean="set_boolean")
 
 	def global_get(self, path, **kwargs):
+		"""
+		Getter for retrieving settings not managed by the plugin itself from the core settings structure. Use this
+		to access global settings outside of your plugin.
+
+		Directly forwards to :func:`octoprint.settings.Settings.get`.
+		"""
 		return self.settings.get(path, **kwargs)
 
 	def global_get_int(self, path, **kwargs):
+		"""
+		Like :func:`global_get` but directly forwards to :func:`octoprint.settings.Settings.getInt`.
+		"""
 		return self.settings.getInt(path, **kwargs)
 
 	def global_get_float(self, path, **kwargs):
+		"""
+		Like :func:`global_get` but directly forwards to :func:`octoprint.settings.Settings.getFloat`.
+		"""
 		return self.settings.getFloat(path, **kwargs)
 
 	def global_get_boolean(self, path, **kwargs):
+		"""
+		Like :func:`global_get` but directly orwards to :func:`octoprint.settings.Settings.getBoolean`.
+		"""
 		return self.settings.getBoolean(path, **kwargs)
 
 	def global_set(self, path, value, **kwargs):
+		"""
+		Setter for modifying settings not managed by the plugin itself on the core settings structure. Use this
+		to modify global settings outside of your plugin.
+
+		Directly forwards to :func:`octoprint.settings.Settings.set`.
+		"""
 		self.settings.set(path, value, **kwargs)
 
 	def global_set_int(self, path, value, **kwargs):
+		"""
+		Like :func:`global_set` but directly forwards to :func:`octoprint.settings.Settings.setInt`.
+		"""
 		self.settings.setInt(path, value, **kwargs)
 
 	def global_set_float(self, path, value, **kwargs):
+		"""
+		Like :func:`global_set` but directly forwards to :func:`octoprint.settings.Settings.setFloat`.
+		"""
 		self.settings.setFloat(path, value, **kwargs)
 
 	def global_set_boolean(self, path, value, **kwargs):
+		"""
+		Like :func:`global_set` but directly forwards to :func:`octoprint.settings.Settings.setBoolean`.
+		"""
 		self.settings.setBoolean(path, value, **kwargs)
 
 	def global_get_basefolder(self, folder_type, **kwargs):
+		"""
+		Retrieves a globally defined basefolder of the given ``folder_type``. Directly forwards to
+		:func:`octoprint.settings.Settings.getBaseFolder`.
+		"""
 		return self.settings.getBaseFolder(folder_type, **kwargs)
 
 	def get_plugin_logfile_path(self, postfix=None):
+		"""
+		Retrieves the path to a logfile specifically for the plugin. If ``postfix`` is not supplied, the logfile
+		will be named ``plugin_<plugin identifier>.log`` and located within the configured ``logs`` folder. If a
+		postfix is supplied, the name will be ``plugin_<plugin identifier>_<postfix>.log`` at the same location.
+
+		Plugins may use this for specific logging tasks. For example, a :class:`~octoprint.plugin.SlicingPlugin` might
+		want to create a log file for logging the output of the slicing engine itself if some debug flag is set.
+
+		Arguments:
+		    postfix (str): Postfix of the logfile for which to create the path. If set, the file name of the log file
+		        will be ``plugin_<plugin identifier>_<postfix>.log``, if not it will be
+		        ``plugin_<plugin identifier>.log``.
+
+		Returns:
+		    str: Absolute path to the log file, directly usable by the plugin.
+		"""
 		filename = "plugin_" + self.plugin_key
 		if postfix is not None:
 			filename += "_" + postfix

src/octoprint/plugin/types.py

@@ -6,7 +6,7 @@ class, :class:`OctoPrintPlugin`.
 Please note that the plugin implementation types are documented in the section
 :ref:`Available plugin mixins <sec-plugins-mixins>`.
 
-.. autoclass: OctoPrintPlugin
+.. autoclass:: OctoPrintPlugin
 
 """
 
@@ -22,21 +22,47 @@ from .core import Plugin
 
 class OctoPrintPlugin(Plugin):
 	"""
+	The parent class of all OctoPrint plugin mixins.
+
 	.. attribute:: _plugin_manager
 
+	   The :class:`~octoprint.plugin.core.PluginManager` instance. Injected by the plugin core system upon
+	   initialization of the implementation.
+
 	.. attribute:: _printer_profile_manager
 
+	   The :class:`~octoprint.printer.profile.PrinterProfileManager` instance. Injected by the plugin core system upon
+	   initialization of the implementation.
+
 	.. attribute:: _event_bus
 
+	   The :class:`~octoprint.events.EventManager` instance. Injected by the plugin core system upon initialization of
+	   the implementation.
+
 	.. attribute:: _analysis_queue
 
+	   The :class:`~octoprint.filemanager.analysis.AnalysisQueue` instance. Injected by the plugin core system upon
+	   initialization of the implementation.
+
 	.. attribute:: _slicing_manager
 
+	   The :class:`~octoprint.slicing.SlicingManager` instance. Injected by the plugin core system upon initialization
+	   of the implementation.
+
 	.. attribute:: _file_manager
 
+	   The :class:`~octoprint.filemanager.FileManager` instance. Injected by the plugin core system upon initialization
+	   of the implementation.
+
 	.. attribute:: _printer
 
+	   The :class:`~octoprint.printer.PrinterInterface` instance. Injected by the plugin core system upon initialization
+	   of the implementation.
+
 	.. attribute:: _app_session_manager
+
+	   The :class:`~octoprint.users.SessionManager` instance. Injected by the plugin core system upon initialization of
+	   the implementation.
 	"""
 
 	pass

src/octoprint/printer/__init__.py

@@ -10,6 +10,9 @@ abstracted version of the actual printer communiciation.
 
 .. autoclass:: PrinterInterface
    :members:
+
+.. autoclass:: PrinterCallback
+   :members:
 """
 
 from __future__ import absolute_import

src/octoprint/util/__init__.py

@@ -22,7 +22,7 @@ import warnings
 logger = logging.getLogger(__name__)
 
 def warning_decorator_factory(warning_type):
-	def specific_warning(message, stacklevel=1, since=None, includedoc=None):
+	def specific_warning(message, stacklevel=1, since=None, includedoc=None, extenddoc=False):
 		def decorator(func):
 			@wraps(func)
 			def func_wrapper(*args, **kwargs):
@@ -33,7 +33,7 @@ def warning_decorator_factory(warning_type):
 
 			if includedoc is not None and since is not None:
 				docstring = "\n.. deprecated:: {since}\n   {message}\n\n".format(since=since, message=includedoc)
-				if hasattr(func_wrapper, "__doc__") and func_wrapper.__doc__ is not None:
+				if extenddoc and hasattr(func_wrapper, "__doc__") and func_wrapper.__doc__ is not None:
 					docstring = func_wrapper.__doc__ + "\n" + docstring
 				func_wrapper.__doc__ = docstring
 
@@ -57,6 +57,8 @@ Arguments:
         happening dynamically from a fixed position to not shadow the real caller (e.g. in case of overridden
         ``getattr`` methods).
     includedoc (string): Message about the deprecation to include in the wrapped function's docstring.
+    extenddoc (boolean): If True the original docstring of the wrapped function will be extended by the deprecation
+        message, if False (default) it will be replaced with the deprecation message.
     since (string): Version since when the function was deprecated, must be present for the docstring to get extended.
 
 Returns:
@@ -77,6 +79,8 @@ Arguments:
         meaning the direct caller of the method. It might make sense to increase this in case of the function call
         happening dynamically from a fixed position to not shadow the real caller (e.g. in case of overridden
         ``getattr`` methods).
+    extenddoc (boolean): If True the original docstring of the wrapped function will be extended by the deprecation
+        message, if False (default) it will be replaced with the deprecation message.
     includedoc (string): Message about the deprecation to include in the wrapped function's docstring.
     since (string): Version since when the function was deprecated, must be present for the docstring to get extended.