pingu_98/MrDraw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Even more documentation of the internal modules

Browse source
This commit is contained in:
Gina Häußge 2015-03-06 01:42:49 +01:00
parent 975cc5ccfc
commit d447308ef0
16 changed files with 158 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/conf.py
View file

@ -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.

6
docs/development/index.rst
View file

@ -4,7 +4,7 @@
Development
###########
.. toctree::
:maxdepth: 3
.. todo::
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.

8
docs/development/interface/printer.rst
View file

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

2
docs/index.rst
View file

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

11
docs/development/interface/filemanager.rst → docs/modules/filemanager.rst
View file

@ -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
-----------------------------

8
docs/development/interface/index.rst → docs/modules/index.rst
View file

@ -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

7
docs/development/interface/plugin.rst → docs/modules/plugin.rst
View file

@ -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

6
docs/modules/printer.rst Normal file
View file

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

6
docs/modules/settings.rst Normal file
View file

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

2
docs/development/interface/util.rst → docs/modules/util.rst
View file

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

2
docs/plugins/index.rst
View file

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

2
docs/plugins/mixins.rst
View file

@ -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:

107
src/octoprint/plugin/__init__.py
View file

@ -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 boolean merged: whether to merge the returned result with the default settings (True) or not (False, default)
:return: the retrieved settings value
:param path: The path for which to retrieve the value.
:type path: list, tuple
: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

28
src/octoprint/plugin/types.py
View file

@ -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

3
src/octoprint/printer/__init__.py
View file

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

8
src/octoprint/util/__init__.py
View file

@ -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.