Change readthedocs sphinx theme. (#727)

* Change documentation theme.

* Update titles.

* Add note directives.

* Update links and directives.

.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

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 <https://learn.microsoft.com/ja-jp/windows/win32/wmisdk/constructing-a-moniker-string>`_:
 
     .. 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 <server.html#implementing-com-methods>`_
+    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 <https://docs.python.org/3/library/enum.html#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

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

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,15 +102,15 @@
 
 # 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
 # documentation.
 # 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
 # "<project> v<release> documentation".

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 <https://docs.python.org/3/library/ctypes.html>`_ 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 <https://pypi.org/project/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 <https://github.com/enthought/comtypes>`_.
+Releases can be downloaded from the `GitHub releases <https://github.com/enthought/comtypes/releases>`_
+section.
 
 
-.. |comtypes| replace:: ``comtypes``
+Installation
+************
 
-.. |ctypes| replace:: ``ctypes``
+|comtypes| is available on `PyPI <https://pypi.org/project/comtypes>`_ 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``

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);