Docs update for 0.8.0 - part 1 (#196)

* Start API Reference page
  Documentation of keep.running, keep.presenting and dbus related
  things.
  
* Switch from napoleon to numpydoc. This looks nicer for few reasons.
  (1) The napoleon adds bullet points to parameter lists. These are
  unwanted.
  (2) Napoleon adds an en dash between parameter type and description,
  which is unwanted.
  (3) Napoleon makes description start from the same line as the
  parameter name and type. This is also unwanted.
  
* Update Sphinx~=5.0 -> ~=7.0
* Update myst_parser~=1.0.0 -> ~=2.0.0
* Add bunch of cross-links.

Author: fohrloop

docs/source/api-reference.md

@@ -0,0 +1,31 @@
+# API Reference 
+
+```{eval-rst}
+
+.. autosummary::
+
+    wakepy.keep.running
+    wakepy.keep.presenting
+    wakepy.DbusAdapter
+
+Wakepy Modes
+-------------
+.. autofunction:: wakepy.keep.running 
+.. autofunction:: wakepy.keep.presenting 
+
+DBus Adapter
+-------------
+Dbus adapters are an advanced concept of wakepy. They would be used in such a case where wants to use other D-Bus python library than the default (which is `jeepney <https://jeepney.readthedocs.io/>`_).
+
+.. autoclass:: wakepy.DbusAdapter
+    :members:
+
+.. autoclass:: wakepy.core.DbusMethodCall
+    :members:
+
+.. autoclass:: wakepy.core.DbusMethod
+    :members:
+    :exclude-members: count, index
+
+
+```  

docs/source/conf.py

@@ -22,17 +22,17 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    # Markdown (MyST) format support for Sphinx
     "myst_parser",
-    # TODO: Check also autodoc2
-    # https://myst-parser.readthedocs.io/en/latest/syntax/code_and_apis.html#sphinx-autodoc2
-    "sphinx.ext.autodoc",
-    "sphinx.ext.napoleon",
+    # Adds support for NumPy style docstrings for autodoc
+    "numpydoc",
     # Sphinx Design adds some sphinx directives for UI components
     # See: https://sphinx-design.readthedocs.io/
     "sphinx_design",
     # Add copy button to code blocks
     # See: https://sphinx-copybutton.readthedocs.io/
     "sphinx_copybutton",
+    "sphinx.ext.autosummary",
 ]
 
 # Needed by sphinx_design
@@ -61,15 +61,9 @@
 # Ref2: https://jupyterbook.org/en/stable/content/figures.html#numbered-references
 numfig = True
 
-
-# Add a border around Examples. Might or might not look good, depending on the
-# used theme.
-# See: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#confval-napoleon_use_admonition_for_examples
-napoleon_use_admonition_for_examples = True
-napoleon_google_docstring = False
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
+html_static_path = ["_static"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -95,3 +89,8 @@
     "pygment_light_style": "friendly",
     "pygment_dark_style": "lightbulb",
 }
+
+# Whether to create a Sphinx table of contents for the lists of class methods
+# and attributes. If a table of contents is made, Sphinx expects each entry to
+# have a separate page. True by default.
+numpydoc_class_members_toctree = False

docs/source/index.md

@@ -78,10 +78,9 @@ The table above only considers the *automatic* actions (go to sleep, start scree
 :numbered: -1
 :titlesonly:
 
-quickstart
 modes
 methods-reference
-
+api-reference
 cli-api
 ```
 

docs/source/modes.md

@@ -31,10 +31,8 @@ with keep.running() as m:
 (keep-running-mode)=
 ## keep.running
 
-
-**Does keep.running prevent manually putting system to sleep?** All the methods, if not otherwise specified, only prevent the *automatic, idle timer timeout based* sleeping, so it is still possible to put system to sleep by selecting Suspend/Sleep from a menu, closing the laptop lid or pressing a power key, for example. One exception is systemd mask method on Linux, which prevents suspend altogether.
-
-**Can I lock my computer after entered `keep.running` mode?**: Yes, and you probably should, if you're not near your computer. The programs will continue execution regardless of the lock.
+While `keep.running` mode is activated, the system may not automatically go to sleep (or
+suspend) meaning that programs will continue running and can use CPU.
 
 
 | Platform | DE    | Method                                                             |
@@ -43,13 +41,35 @@ with keep.running() as m:
 | MacOS    | *     | [caffeinate](#keep-running-macos-caffeinate)                       |
 | Windows  | *     | [SetThreadExecutionState](#keep-running-windows-stes)              |
 
+
+Does keep.running prevent manually putting system to sleep?
+: Only the  automatical, idle timer timeout based sleep / suspend is prevented; Will not
+prevent user manually entering sleep from a menu, by closing a laptop lid or by pressing
+a power button, for example.
+
+Can I lock my computer after entered `keep.running` mode?
+: Yes, and you probably should, if you're not near your computer. The program will
+continue execution regardless of the lock.
+
+What about automatical lockscreen / screensaver?
+: The system may still automatically log out user, enable lockscreen or turn off the
+display. Automatic lock screen is not guaranteed, but it is  not prevented in any way.
+
+What happens id the process holding the lock dies?
+: The lock is automatically removed. There are no methods in keep.running mode which for
+example would perform system-wide configuration changes or anything which would need
+manual reversal.
+
+
+
 (keep-presenting-mode)=
 ## keep.presenting
 
+While `keep.presenting` mode is activated, the system may not automatically go to sleep (or
+suspend) meaning that programs will continue running and can use CPU. In addition to
+that, automatic start of screensaver & screenlock are prevented, meaning that you can 
+show content in the `keep.presenting` mode.
 
-**Does keep.presenting prevent manually putting system to sleep?** All the methods, if not otherwise specified, only prevent the *automatic, idle timer timeout based*  sleeping and screensaver/screenlock, so it is still possible to put system to sleep by selecting Suspend/Sleep from a menu, closing the laptop lid or pressing a power key, for example. It is also possible to manually start the screenlock/screensaver while presenting mode is on. 
-
-**Is my computer locked automatically in `keep.presenting` mode?**: No. Entering a screenlock automatically would stop presenting the content. 
 
 | Platform | DE              | Method                                                                      |
 | -------- | --------------- | --------------------------------------------------------------------------- |
@@ -58,6 +78,21 @@ with keep.running() as m:
 | MacOS    | *               | [caffeinate](#keep-presenting-macos-caffeinate)                             |
 | Windows  | *               | [SetThreadExecutionState](#keep-presenting-windows-stes)                    |
 
+Does keep.presenting prevent manually putting system to sleep?
+: Only the  automatical, idle timer timeout based sleep / suspend is prevented; Will not
+prevent user manually entering sleep from a menu, by closing a laptop lid or by pressing
+a power button, for example.
+
+Can I still manually start lockscreen / screensaver?
+: Yes. Only the idle timer based screensaver / lockscreen is prevented. Note that
+manually entering screensaver does not deactivate the mode.
+
+
+What happens id the process holding the lock dies?
+: The lock is automatically removed. There are no methods in keep.presenting mode which for
+example would perform system-wide configuration changes or anything which would need
+manual reversal.
+
 
 ## General questions
 **What if the process holding the lock dies?**: The lock is automatically removed. 

pyproject.toml

@@ -32,10 +32,10 @@ classifiers = [
 
 [project.optional-dependencies]
 doc = [
-    "sphinx~=5.0",
-    "sphinx_design~=0.4.1",
+    "sphinx~=7.0",
+    "sphinx_design>0.4.1",
     "sphinx-copybutton~=0.5.2",
-    "myst-parser~=1.0.0",
+    "myst-parser~=2.0.0",
     "sphinx-book-theme~=1.1.0",
 ]
 dev = [

wakepy/core/dbus.py

@@ -79,23 +79,23 @@ class DbusMethod(NamedTuple):
     signature: str | None
     """The signature for the method input parameters.
 
-    The types are: (Conventional name, ASCII type-code, meaning)
+    The types are: (Conventional name, ASCII type-code, meaning)::
     
-    BYTE	y (121)	Unsigned 8-bit integer
-    BOOLEAN	b (98)	Boolean value: 0 is false, 1 is true
-    INT16	n (110)	Signed 16-bit integer
-    UINT16	q (113)	Unsigned 16-bit integer
-    INT32	i (105)	Signed 32-bit integer
-    UINT32	u (117)	Unsigned 32-bit integer
-    INT64	x (120)	Signed 64-bit integer
-    UINT64	t (116)	Unsigned 64-bit integer
-    DOUBLE	d (100)	IEEE 754 double-precision floating point
-    UNIX_FD	h (104)	Unsigned 32-bit integer representing an index into an
-                    out-of-band array of file descriptors, transferred via some
-                    platform-specific mechanism
-    STRING  s (115) String
+        BYTE	y (121)	Unsigned 8-bit integer
+        BOOLEAN	b (98)	Boolean value: 0 is false, 1 is true
+        INT16	n (110)	Signed 16-bit integer
+        UINT16	q (113)	Unsigned 16-bit integer
+        INT32	i (105)	Signed 32-bit integer
+        UINT32	u (117)	Unsigned 32-bit integer
+        INT64	x (120)	Signed 64-bit integer
+        UINT64	t (116)	Unsigned 64-bit integer
+        DOUBLE	d (100)	IEEE 754 double-precision floating point
+        UNIX_FD	h (104)	Unsigned 32-bit integer representing an index into an
+                        out-of-band array of file descriptors, transferred via some
+                        platform-specific mechanism
+        STRING  s (115) String
     
-    Ref: https://dbus.freedesktop.org/doc/dbus-specification.html
+    Ref: `dbus-specification <https://dbus.freedesktop.org/doc/dbus-specification.html>`_
     """
     params: Optional[tuple[str, ...]] = None
     """The names of the input arguments defined by the `signature`.
@@ -165,11 +165,18 @@ def of(
         )
 
     def completely_defined(self) -> bool:
+        """Check if the DbusMethod is completely defined."""
         return all(
             x is not None for x in (self.service, self.path, self.interface, self.bus)
         )
 
     def to_call(self, args: CallArguments = None) -> DbusMethodCall:
+        """Convert to :class:`~wakepy.core.DbusMethodCall`.
+
+        Parameters
+        ----------
+        args:
+            The arguments to the D-Bus Method call."""
         return DbusMethodCall(self, args)
 
 
@@ -188,7 +195,7 @@ class DbusMethodCall:
     """
 
     args: Tuple[Any, ...]
-    """The method args (positional). This is used"""
+    """The method args (positional)."""
 
     def __init__(self, method: DbusMethod, args: CallArguments = None):
         """Converts the `args` argument is converted into a tuple and makes it
@@ -201,9 +208,9 @@ def __init__(self, method: DbusMethod, args: CallArguments = None):
         self.args = self._args_as_tuple(args, method)
 
     def get_kwargs(self) -> dict[str, Any] | None:
-        """Get a keyword-argument representation (dict) of the self.args. If
-        the DbusMethod (self.method) does not have params defined, returns
-        None."""
+        """Get a keyword-argument representation (dict) of the
+        :attr:`~wakepy.core.DbusMethodCall.args`. If the DbusMethod
+        (self.method) does not have params defined, returns None."""
         if self.method.params is None:
             return None
         assert isinstance(self.method.params, tuple)
@@ -262,18 +269,24 @@ class DbusAdapter:
     subclass is usually an implementation for a DbusAdapter using single
     python (dbus-)library.
 
-    When subclassing, implement the .process(call) method. The call
-    (DbusMethodCall) tells which bus to use (session/system/custom addr), and
-    therefore the connection must be created within the .process() call (this
-    can of course be cached).
+    When subclassing, implement the :func:`~wakepy.DbusAdapter.process`
+    method.
 
     The __init__() should not take any arguments, and it may raise any subtype
     of Exception, which simply means that the DbusAdapter may not be used. The
     Exception will be omitted if using the high-level API of wakepy.
     """
 
     def process(self, call: DbusMethodCall):
-        ...
+        """Processes a :class:`~wakepy.core.DbusMethodCall`.
+
+        Parameters
+        ----------
+        call: DbusMethodCall
+          Represents a D-Bus method call with its arguments. As it tells which
+          bus to use (session / system / custom addr), the connection must be
+          created within the :func:`~wakepy.DbusAdapter.process` call (this may
+          of course be cached)."""
 
 
 def get_dbus_adapter(

wakepy/modes/keep.py

@@ -23,27 +23,7 @@ def running(
 ) -> Mode:
     """Create a wakepy mode (a context manager) for keeping programs running.
 
-    Properties
-    ----------
-    1) The system may not go to sleep meaning that programs will continue
-       running and can use CPU.
-    2) Does prevent only the automatical, idle timer timeout based sleep /
-       suspend; Will not prevent user manually entering sleep from a menu, by
-       closing a laptop lid or by pressing a power button, for example.
-    3) System may still automatically log out user, enable lockscreen
-       or turn off the display.
-    4) If the process holding the lock dies, the lock is automatically removed.
-       There are no methods in keep.running mode which for example would
-       perform system-wide configuration changes or anything which would need
-       manual reversal.
-
-    Usage
-    -----
-
-    ```
-    with keep.running() as k:
-        # do something that takes a long time.
-    ```
+    :ref:`Documentation of keep.running mode. <keep-running-mode>`
 
     Parameters
     ----------
@@ -73,22 +53,29 @@ def running(
         and may occur only once in the priority order, and cannot be part of a
         set. If asterisk is not part of the `methods_priority`, it will be
         added as the last element automatically.
-    on_fail:
+    on_fail: str | callable
         Determines what to do in case mode activation fails. Valid options are:
         "error", "warn", "pass" and a callable. If the option is "error",
         raises wakepy.ActivationError. Is selected "warn", issues warning. If
         "pass", does nothing. If `on_fail` is a callable, it must take one
         positional argument: result, which is an instance of ActivationResult.
         The ActivationResult contains more detailed information about the
         activation process.
-    dbus_adapter:
-        Optional argument which can be used to define a customer DBus adapter.
+    dbus_adapter: class or sequence of classes
+        Optional argument which can be used to define a custom DBus adapter.
+        If given, should be a subclass of :class:`~wakepy.DbusAdapter`, or a
+        list of such.
 
     Returns
     -------
     keep_running_mode: Mode
         The context manager for keeping a system running.
 
+
+    Examples
+    --------
+    >>> with keep.running() as k:
+    >>>     # do something that takes a long time.
     """
     return create_mode(
         modename=ModeName.KEEP_RUNNING,
@@ -110,12 +97,7 @@ def presenting(
     """Create a wakepy mode (a context manager) for keeping a system running
     and showing content.
 
-    Usage:
-
-    ```
-    with keep.presenting() as k:
-        # do something that takes a long time.
-    ```
+    :ref:`Documentation of keep.presenting mode. <keep-presenting-mode>`
 
     Parameters
     ----------
@@ -153,13 +135,21 @@ def presenting(
         positional argument: result, which is an instance of ActivationResult.
         The ActivationResult contains more detailed information about the
         activation process.
-    dbus_adapter:
-        Optional argument which can be used to define a customer DBus adapter.
+    dbus_adapter: class or sequence of classes
+        Optional argument which can be used to define a custom DBus adapter.
+        If given, should be a subclass of :class:`~wakepy.DbusAdapter`, or a
+        list of such.
 
     Returns
     -------
     keep_presenting_mode: Mode
         The context manager for keeping a system presenting content.
+
+    Examples
+    --------
+    >>> with keep.presenting() as k:
+    >>>     # do something that takes a long time.
+
     """
     return create_mode(
         modename=ModeName.KEEP_PRESENTING,