diff options
author | Simon McVittie <smcv@collabora.com> | 2018-05-02 11:08:09 +0100 |
---|---|---|
committer | Simon McVittie <smcv@collabora.com> | 2018-05-02 11:08:16 +0100 |
commit | 6c630a819f6504d48a3a205ab323b2d0458913e5 (patch) | |
tree | ea27051ef5ac3d8211892eed81b301f9d1fec34a /doc | |
parent | 2d7f71cc7002b5d968f83adffe09e2fc8fd63eb5 (diff) |
Convert documentation from epydoc to Sphinx
Signed-off-by: Simon McVittie <smcv@collabora.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/HACKING.txt | 6 | ||||
-rw-r--r-- | doc/PY3PORT.txt | 6 | ||||
-rw-r--r-- | doc/_static/.gitignore | 0 | ||||
-rw-r--r-- | doc/conf.py | 165 | ||||
-rw-r--r-- | doc/dbus.bus.rst | 7 | ||||
-rw-r--r-- | doc/dbus.connection.rst | 7 | ||||
-rw-r--r-- | doc/dbus.decorators.rst | 7 | ||||
-rw-r--r-- | doc/dbus.exceptions.rst | 7 | ||||
-rw-r--r-- | doc/dbus.gi_service.rst | 7 | ||||
-rw-r--r-- | doc/dbus.glib.rst | 7 | ||||
-rw-r--r-- | doc/dbus.gobject_service.rst | 36 | ||||
-rw-r--r-- | doc/dbus.lowlevel.rst | 7 | ||||
-rw-r--r-- | doc/dbus.mainloop.rst | 18 | ||||
-rw-r--r-- | doc/dbus.proxies.rst | 7 | ||||
-rw-r--r-- | doc/dbus.rst | 35 | ||||
-rw-r--r-- | doc/dbus.server.rst | 7 | ||||
-rw-r--r-- | doc/dbus.service.rst | 7 | ||||
-rw-r--r-- | doc/dbus.types.rst | 7 | ||||
-rw-r--r-- | doc/index.rst | 53 | ||||
-rw-r--r-- | doc/news.rst | 5 |
20 files changed, 395 insertions, 6 deletions
diff --git a/doc/HACKING.txt b/doc/HACKING.txt index c019198..b53655c 100644 --- a/doc/HACKING.txt +++ b/doc/HACKING.txt @@ -1,6 +1,6 @@ -========================================= -D-Bus Python bindings - notes for hackers -========================================= +=============== +Developer notes +=============== :Author: Simon McVittie, `Collabora`_ :Date: 2007-01-24 diff --git a/doc/PY3PORT.txt b/doc/PY3PORT.txt index a028153..e159849 100644 --- a/doc/PY3PORT.txt +++ b/doc/PY3PORT.txt @@ -1,6 +1,6 @@ -=============================== -Porting python-dbus to Python 3 -=============================== +=================== +Porting to Python 3 +=================== This is an experimental port to Python 3.x where x >= 2. There are lots of great sources for porting C extensions to Python 3, including: diff --git a/doc/_static/.gitignore b/doc/_static/.gitignore new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/doc/_static/.gitignore diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..f094a26 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,165 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/stable/config + +# -- Path setup -------------------------------------------------------------- + +import os +import sys + +sys.path.insert(0, + os.path.join( + os.environ.get('abs_top_builddir', os.path.abspath('..')), + '.libs', + ), +) +sys.path.insert(0, os.environ.get('abs_top_srcdir', os.path.abspath('..'))) + +import _dbus_bindings + +# -- Project information ----------------------------------------------------- + +project = u'dbus-python' +copyright = u'2003-2018, D-Bus contributors' +author = u'D-Bus contributors' + +# The short X.Y version +version = _dbus_bindings.__version__ +# The full version, including alpha/beta/rc tags +release = version + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# 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.autodoc', + 'sphinx.ext.coverage', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = ['.rst', '.txt'] + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'dbus-python' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'dbus-python.tex', u'dbus-python Documentation', + u'D-Bus contributors', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'dbus-python', u'dbus-python Documentation', + [author], 3) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'dbus-python', u'dbus-python Documentation', + author, 'dbus-python', + 'Python bindings for the reference implementation of D-Bus.', + 'Miscellaneous'), +] + + +# -- Extension configuration ------------------------------------------------- diff --git a/doc/dbus.bus.rst b/doc/dbus.bus.rst new file mode 100644 index 0000000..1f78f3e --- /dev/null +++ b/doc/dbus.bus.rst @@ -0,0 +1,7 @@ +dbus.bus module +=============== + +.. automodule:: dbus.bus + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/dbus.connection.rst b/doc/dbus.connection.rst new file mode 100644 index 0000000..7b78212 --- /dev/null +++ b/doc/dbus.connection.rst @@ -0,0 +1,7 @@ +dbus.connection module +====================== + +.. automodule:: dbus.connection + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/dbus.decorators.rst b/doc/dbus.decorators.rst new file mode 100644 index 0000000..3f6625c --- /dev/null +++ b/doc/dbus.decorators.rst @@ -0,0 +1,7 @@ +dbus.decorators module +---------------------- + +.. automodule:: dbus.decorators + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/dbus.exceptions.rst b/doc/dbus.exceptions.rst new file mode 100644 index 0000000..fea743c --- /dev/null +++ b/doc/dbus.exceptions.rst @@ -0,0 +1,7 @@ +dbus.exceptions module +---------------------- + +.. automodule:: dbus.exceptions + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/dbus.gi_service.rst b/doc/dbus.gi_service.rst new file mode 100644 index 0000000..945d5a0 --- /dev/null +++ b/doc/dbus.gi_service.rst @@ -0,0 +1,7 @@ +dbus.gi\_service module +----------------------- + +.. automodule:: dbus.gi_service + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/dbus.glib.rst b/doc/dbus.glib.rst new file mode 100644 index 0000000..20958be --- /dev/null +++ b/doc/dbus.glib.rst @@ -0,0 +1,7 @@ +dbus.glib module +---------------- + +.. automodule:: dbus.glib + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/dbus.gobject_service.rst b/doc/dbus.gobject_service.rst new file mode 100644 index 0000000..b1ff1be --- /dev/null +++ b/doc/dbus.gobject_service.rst @@ -0,0 +1,36 @@ +.. This is not done via automodule because it cannot be imported in +.. Python 3. + +dbus.gobject\_service module +---------------------------- + +.. py:module:: gobject_service + +This module is only available when using Python 2, and is deprecated. + +.. py:class:: ExportedGObjectType(cls, name, bases, dct) + + A metaclass which inherits from both GObjectMeta and + `dbus.service.InterfaceType`. Used as the metaclass for + `ExportedGObject`. + +.. py:class:: ExportedGObject(self, conn=None, object_path=None, **kwargs) + + A GObject which is exported on the D-Bus. + + Because GObject and `dbus.service.Object` both have custom metaclasses, + the naive approach using simple multiple inheritance won't work. This + class has `ExportedGObjectType` as its metaclass, which is sufficient + to make it work correctly. + + :param dbus.connection.Connection conn: + The D-Bus connection or bus + :param str object_path: + The object path at which to register this object. + :keyword dbus.service.BusName bus_name: + A bus name to be held on behalf of this object, or None. + :keyword dict gobject_properties: + GObject properties to be set on the constructed object. + + Any unrecognised keyword arguments will also be interpreted + as GObject properties. diff --git a/doc/dbus.lowlevel.rst b/doc/dbus.lowlevel.rst new file mode 100644 index 0000000..74e5f47 --- /dev/null +++ b/doc/dbus.lowlevel.rst @@ -0,0 +1,7 @@ +dbus.lowlevel module +-------------------- + +.. automodule:: dbus.lowlevel + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/dbus.mainloop.rst b/doc/dbus.mainloop.rst new file mode 100644 index 0000000..14bbf14 --- /dev/null +++ b/doc/dbus.mainloop.rst @@ -0,0 +1,18 @@ +dbus.mainloop package +===================== + +Module contents +--------------- + +.. automodule:: dbus.mainloop + :members: + :undoc-members: + :show-inheritance: + +dbus.mainloop.glib module +------------------------- + +.. automodule:: dbus.mainloop.glib + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/dbus.proxies.rst b/doc/dbus.proxies.rst new file mode 100644 index 0000000..8e4e8e3 --- /dev/null +++ b/doc/dbus.proxies.rst @@ -0,0 +1,7 @@ +dbus.proxies module +------------------- + +.. automodule:: dbus.proxies + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/dbus.rst b/doc/dbus.rst new file mode 100644 index 0000000..2b2ab96 --- /dev/null +++ b/doc/dbus.rst @@ -0,0 +1,35 @@ +dbus package API reference +========================== + +Submodules +---------- + +.. toctree:: + + dbus.bus + dbus.connection + dbus.decorators + dbus.exceptions + dbus.gi_service + dbus.lowlevel + dbus.mainloop + dbus.proxies + dbus.server + dbus.service + dbus.types + +Deprecated submodules +--------------------- + +.. toctree:: + + dbus.glib + dbus.gobject_service + +Module contents +--------------- + +.. automodule:: dbus + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/dbus.server.rst b/doc/dbus.server.rst new file mode 100644 index 0000000..c0d94c6 --- /dev/null +++ b/doc/dbus.server.rst @@ -0,0 +1,7 @@ +dbus.server module +------------------ + +.. automodule:: dbus.server + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/dbus.service.rst b/doc/dbus.service.rst new file mode 100644 index 0000000..61958d6 --- /dev/null +++ b/doc/dbus.service.rst @@ -0,0 +1,7 @@ +dbus.service module +------------------- + +.. automodule:: dbus.service + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/dbus.types.rst b/doc/dbus.types.rst new file mode 100644 index 0000000..c02c788 --- /dev/null +++ b/doc/dbus.types.rst @@ -0,0 +1,7 @@ +dbus.types module +----------------- + +.. automodule:: dbus.types + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..ca754b5 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,53 @@ +======================================= +dbus-python_: Python bindings for D-Bus +======================================= + +.. _dbus-python: http://www.freedesktop.org/wiki/Software/DBusBindings#python + +dbus-python is a Python binding for ``dbus``, the reference implementation +of the D-Bus protocol. + +Problems and alternatives +========================= + +dbus-python might not be the best D-Bus binding for you to use. dbus-python +does not follow the principle of "In the face of ambiguity, refuse the +temptation to guess", and can't be changed to not do so without seriously +breaking compatibility. + +In addition, it uses libdbus (which has known problems with multi-threaded +use) and attempts to be main-loop-agnostic (which means you have to select +a suitable main loop for your application). + +Alternative ways to get your Python code onto D-Bus include: + +* GDBus, part of the GIO module of `GLib`_, via GObject-Introspection and + `PyGI`_ (uses the GLib main loop and object model) + +* QtDBus, part of `Qt`_, via `PyQt`_ (uses the Qt main loop and object model) + +.. _GLib: http://developer.gnome.org/glib/ +.. _PyGI: https://live.gnome.org/PyGObject +.. _Qt: https://qt.nokia.com/ +.. _PyQT: http://www.riverbankcomputing.co.uk/software/pyqt/intro + +Documentation +============= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + tutorial + dbus + PY3PORT + news + HACKING + API_CHANGES + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/news.rst b/doc/news.rst new file mode 100644 index 0000000..249c431 --- /dev/null +++ b/doc/news.rst @@ -0,0 +1,5 @@ +=============== +Release history +=============== + +.. include:: ../NEWS |