diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 7cb0dff7..4895af2c 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -18,6 +18,6 @@ sphinx: # Optionally, but recommended, # declare the Python requirements required to build your documentation # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html -# python: -# install: -# - requirements: docs/requirements.txt +python: + install: + - requirements: docs/requirements.txt diff --git a/docs/source/client.rst b/docs/source/client.rst index 925f63d1..b790279c 100644 --- a/docs/source/client.rst +++ b/docs/source/client.rst @@ -1,6 +1,6 @@ -########################### -The comtypes.client package -########################### +############################### +The ``comtypes.client`` package +############################### The ``comtypes.client`` package implements the high-level |comtypes| functionality. @@ -47,8 +47,8 @@ access COM objects. Create a named COM object and returns an interface pointer to it. For the interpretation of ``displayname`` consult the Microsoft documentation for the Windows ``CoGetObject`` function. - ``"winmgmts:"``, for example, is the displayname for `WMI - monikers`_: + ``"winmgmts:"``, for example, is the displayname for + `WMI monikers `_: .. sourcecode:: python @@ -258,8 +258,12 @@ VT_INT``, or an array a strings with typecode ``VT_ARRAY | VT_BSTR``. To create these variants you must pass an instance of the Python ``array.array`` with the correct Python typecode to the COM method. -Note that NumPy arrays are also an option here, as is described in -the following section. + +.. note:: + + NumPy arrays are also an option, as described in the + :doc:`npsupport` document. + The mapping of the ``array.array`` typecode to the ``VARIANT`` typecode is defined in the ``comtypes.automation`` module by a @@ -336,9 +340,11 @@ Some COM objects support events, which allows them to notify the user of the object when something happens. The standard COM mechanism is based on so-called *connection points*. -Note: For the rules that you should observe when implementing event -handlers you should read the implementing_COM_methods_ section in the -|comtypes| server document. +.. note:: + + For the rules that you should observe when implementing event + handlers you should read the :doc:`server` document. + ``GetEvents(source, sink, interface=None)`` This functions connects an event sink to the COM object @@ -473,9 +479,13 @@ and passes it as second parameter to the ``GetEvents()`` function: FontChanged Name -Note that event handler methods support the same calling convention as -COM method implementations in |comtypes|. So the remarks about -implementing_COM_methods_ should be observed. +.. note:: + + Event handler methods support the same calling convention as COM + method implementations in |comtypes|. So the remarks about the + `"Implementing COM methods" section in the server document `_ + should be observed. + Typelibraries ************* @@ -529,9 +539,9 @@ from COM typelibraries. abstracted alias ``__wrapper_module__``, also imports interface classes, coclasses, constants, and structures from the wrapper module, and defines enumerations from typeinfo of the typelibrary - using `enum.IntFlag`_. The friendly module can be imported - easier than the wrapper module because the module name is easier - to type and read. + using `enum.IntFlag `_. + The friendly module can be imported easier than the wrapper + module because the module name is easier to type and read. For example, the typelibrary for Scripting Runtime has the name ``Scripting`` (this is the name specified in the type library @@ -656,9 +666,3 @@ XXX describe logging, gen_dir, wrap, _manage (?) .. |comtypes| replace:: ``comtypes`` - -.. _`WMI monikers`: http://www.microsoft.com/technet/scriptcenter/guide/sas_wmi_jgfx.mspx?mfr=true - -.. _`enum.IntFlag`: https://docs.python.org/3/library/enum.html#enum.IntFlag - -.. _implementing_COM_methods: server.html#implementing-com-methods diff --git a/docs/source/com_interfaces.rst b/docs/source/com_interfaces.rst index 0d96bfd5..c8fbe4c2 100644 --- a/docs/source/com_interfaces.rst +++ b/docs/source/com_interfaces.rst @@ -1,6 +1,6 @@ -####################### -comtypes COM interfaces -####################### +########################### +``comtypes`` COM interfaces +########################### .. contents:: @@ -69,8 +69,10 @@ attributes: ISomeInterface._methods_ = [...,] -**Note:** All the other attributes ``_iid_``, ``_idlflags_``, -``_case_insensitive_`` must be defined when ``_methods_`` is set. +.. note:: + + All the other attributes ``_iid_``, ``_idlflags_``, + ``_case_insensitive_`` must be defined when ``_methods_`` is set. The ``_methods_`` list @@ -255,9 +257,11 @@ interfaces that your COM object implements must be listed in the implement the methods of all the interfaces by writing a Python method for each of them. -**Note**: The ``COMObject`` metaclass provides a default for methods -that are **not** implemented in Python. This default method returns -the standard COM error code ``E_NOTIMPL`` when it is called. +.. note:: + + The ``COMObject`` metaclass provides a default for methods + that are **not** implemented in Python. This default method returns + the standard COM error code ``E_NOTIMPL`` when it is called. To implement the COM method named ``MethodName`` for the interface ``ISomeInterface`` you write a Python method either named ``ISomeInterface_MethodName`` @@ -370,8 +374,11 @@ actual COM method of the object, retrives ``"out"`` parameters from their container(s) and returns them as the result. If the method has exactly one ``"out"`` parameter, this is returned. If the method has two or more ``"out"`` parameters, a tuple of their values is returned. -**Note**: the native return value of the method, usually a ``HRESULT``, -is *not* returned in the presence of "out" parameters. + +.. note:: + + The native return value of the method, usually a ``HRESULT``, + is **not** returned in the presence of "out" parameters. For the ``IProvideClassInfo`` and ``IProvideClassInfo`` COM interfaces mentioned above, the metaclass creates methods with these signatures diff --git a/docs/source/conf.py b/docs/source/conf.py index 8bda0acb..c8538b62 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -14,6 +14,8 @@ import os import sys +import sphinx_rtd_theme + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -32,6 +34,7 @@ "sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.todo", + "sphinx_rtd_theme", "sphinx.ext.doctest", ] @@ -99,7 +102,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "default" +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 @@ -107,7 +110,7 @@ # html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = [] +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". diff --git a/docs/source/index.rst b/docs/source/index.rst index 6b656a1c..6a546b67 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,14 +1,16 @@ -#################### -The comtypes package -#################### +######################## +The ``comtypes`` package +######################## -|comtypes| is a *pure Python* COM package based on the ctypes_ ffi +|comtypes| is a *pure Python* COM package based on the +`ctypes `_ ffi foreign function library. |ctypes| is included in Python 2.5 and later, it is also available for Python 2.4 as separate download. -While the pywin32_ package contains superior client side support -for *dispatch based* COM interfaces, it is not possible to access -*custom* COM interfaces unless they are wrapped in C++-code. +While the `pywin32 `_ package +contains superior client side support for *dispatch based* COM +interfaces, it is not possible to access *custom* COM interfaces +unless they are wrapped in C++-code. The |comtypes| package makes it easy to access and implement both custom and dispatch based COM interfaces. @@ -46,18 +48,22 @@ Chen, Alicia (2012). `"Comtypes: How Dropbox learned to stop worrying and love t Downloads ********* -The |comtypes| project is hosted on github_. Releases can be downloaded from -the github releases_ section. +The |comtypes| project is hosted on `GitHub `_. +Releases can be downloaded from the `GitHub releases `_ +section. -.. |comtypes| replace:: ``comtypes`` +Installation +************ -.. |ctypes| replace:: ``ctypes`` +|comtypes| is available on `PyPI `_ and +can be installed with ``pip``: -.. _ctypes: https://docs.python.org/3/library/ctypes.html +.. sourcecode:: shell -.. _pywin32: https://pypi.org/project/pywin32/ + pip install comtypes -.. _github: https://github.com/enthought/comtypes -.. _releases: https://github.com/enthought/comtypes/releases +.. |comtypes| replace:: ``comtypes`` + +.. |ctypes| replace:: ``ctypes`` diff --git a/docs/source/server.rst b/docs/source/server.rst index 40ee7256..f732acb8 100644 --- a/docs/source/server.rst +++ b/docs/source/server.rst @@ -1,6 +1,6 @@ -######################### -COM servers with comtypes -######################### +############################# +COM servers with ``comtypes`` +############################# The |comtypes| package makes it easy to access and implement both custom and dispatch based COM interfaces. @@ -187,7 +187,7 @@ COM event handlers! In the IDL file, the method signature is defined like this: -.. sourcecode:: c +.. sourcecode:: idl HRESULT MyMethod([in] INT a, [in] INT b, [out, retval] INT *presult);