Docs update (#285)

Another PR for #68 Docs ----- - Add nicer platform support table - Add ActivationWarning to docs - Update the docs front page - Add Tutorial page (on-fail action, which method was used) Other ----- - Add: ActivationWarning. Use that instead of general UserWarning if on-fail action is warning.
fohrloop · May 25, 2024 · d0151a4 · d0151a4
1 parent 8b1b565
commit d0151a4
Show file tree

Hide file tree

Showing 14 changed files with 345 additions and 71 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,10 @@
 - It is now possible to select the used wakepy.Methods with `methods` and
  `omit` and to change the priority order of methods with `methods_priority`.
 
+### Added
+
+- Modes support [on-fail actions](#on-fail-action) ("error", "warn", "pass" or a callable).
+
 ## [0.7.2] (2023-09-27)
 ### Fixed
 - The CLI API on python 3.7 and python 3.8. Thanks to [Aymane11](https://github.com/Aymane11) for [PR #50](https://github.com/fohrloop/wakepy/pull/50)

diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 Cross-platform wakelock / keep-awake / stay-awake written in Python.
 
 ## Supports
-- Python: 3.7 to 3.12
+- Python: 3.7 to 3.13
 - OS: Windows, Linux and macOS
 
 ## What it can do?
@@ -16,7 +16,12 @@ Wakepy has two main modes:
 2. **`keep.presenting`**: same as `keep.running` but keep also the screen awake and prevent automatic screen lock & screensaver  (*e.g.* for showing a video, updating dashboard, monitoring apps, ...)
 <!-- end before docs link -->
 
-
+> [!NOTE]
+> Wakepy API is still experimental 🚧
+> 
+> Since wakepy is still 0.x.x, the API might change without further notice from
+> one release to another. After that, breaking changes should occur only part of
+> a major release (e.g. 1.x.x -> 2.0.0). 
 
 ## Used by
 - [viskillz-blender](https://github.com/viskillz/viskillz-blender) — Generating assets of Mental Cutting Test exercises

diff --git a/docs/source/_static/wakepy-docs.css b/docs/source/_static/wakepy-docs.css
@@ -90,3 +90,32 @@ dl.py > dd > p + ul {
 dl.py > dd > ul {
     margin-bottom: 1.15rem !important;
 }
+
+/* Custom table class for wakepy docs */
+.wakepy-table {
+    width: 100%;
+    border-collapse: collapse;
+    border-radius: 8px;
+    overflow: hidden;
+    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+  }
+
+.wakepy-table th,
+.wakepy-table td {
+  border: 1px solid #ddd;
+  padding: 12px;
+  text-align: left;
+}
+
+.wakepy-table th {
+  background-color: #f6f6f6;
+  font-weight: bold;
+}
+
+.wakepy-table td:first-child {
+  vertical-align: top; /* Align text to the top in the first column */
+}
+
+.wakepy-table td {
+  background-color: #fff;
+}
diff --git a/docs/source/_templates/sbt-sidebar-nav.html b/docs/source/_templates/sbt-sidebar-nav.html
@@ -3,10 +3,10 @@
 theme/sphinx_book_theme/components/sbt-sidebar-nav.html
 #}
 <nav class="bd-links bd-docs-nav" aria-label="Main">
-    {# Custom addition: Add "User Guide:" title.
+    {# Custom addition: Add "New to wakepy?" title.
     This is not possible to add otherwise, as the list comes from
     generate_toctree_html (if not modifying generate_toctree_html)#}
-    <p aria-level="2" class="caption" role="heading"><span class="caption-text">User Guide:</span></p>
+    <p aria-level="2" class="caption" role="heading"><span class="caption-text">New to wakepy?</span></p>
     <div class="bd-toc-item navbar-nav active">
         {% if theme_home_page_in_toc == True %}
         {#- This mimics the pydata theme list style so we can append an extra item at the top #}

diff --git a/docs/source/api-reference.md b/docs/source/api-reference.md
@@ -1,13 +1,22 @@
 <!-- NOTE: If you change the title (API Reference), you must update the code
 in wakepy-docs.js! -->
 # API Reference
+
+```{admonition} Wakepy API is still experimental 🚧
+:class: note
+
+Since wakepy is still 0.x.x, the API might change without further notice from
+one release to another. After that, breaking changes should occur only part of
+a major release (e.g. 1.x.x -> 2.0.0). 
+```
+
+
 ```{eval-rst}
 
 .. autosummary::
 
     wakepy.keep.running
     wakepy.keep.presenting
-    wakepy.DBusAdapter
 
 Wakepy Modes
 -------------
@@ -36,6 +45,9 @@ Wakepy Core
 .. autoclass:: wakepy.ActivationError
     :exclude-members: args, with_traceback
 
+.. autoclass:: wakepy.ActivationWarning
+    :exclude-members: args, with_traceback
+
 .. autoclass:: wakepy.ModeExit
     :exclude-members: args, with_traceback
 

diff --git a/docs/source/index.md b/docs/source/index.md
@@ -1,72 +1,89 @@
-# Quickstart
+# Overview
+
+## What is wakepy?
+
+Wakepy is a package with an Python API and a CLI tool for *keeping a system awake*. Namely:
+
+⌛ **Keeping CPU awake**:  For long running tasks. Inhibit the automatic, timer based sleep or suspend action, but allow screenlock and screensaver turning on and monitor turning off. (See: [keep.running](#keep-running-mode))
+
+🖥️ **Keeping screen awake**:  For long running tasks which require also the screen on and screenlock and screensaver inhibited. (See: [keep.presenting](#keep-presenting-mode))
+
+
+## Supported platforms
+
+Wakepy may keep the following systems awake:
+
+
+<table class="wakepy-table">
+  <colgroup>
+    <col style="width: 25%;">
+    <col style="width: 75%;">
+  </colgroup>
+  <thead>
+    <tr>
+      <th>Platform</th>
+      <th>Details</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td class="hoverable" rowspan="2">Windows</td>
+      <td>Windows XP to Windows 11</td>
+    </tr>
+    <tr>
+      <td>Windows Server 2003 or higher</td>
+    </tr>
+    <tr>
+      <td>Mac OS</td>
+      <td>Mac OS X 10.8 Mountain Lion (July 2012) or newer</td>
+    </tr>
+    <tr>
+      <td class="hoverable" rowspan="2">Linux<sup>[1]</sup></td>
+      <td>Distributions using <a href="https://en.wikipedia.org/wiki/GNOME">GNOME</a></td>
+    </tr>
+    <tr>
+      <td>Desktop Environments which implement the <a href="https://en.wikipedia.org/wiki/Freedesktop.org">Freedesktop.org</a> ScreenSaver interface (<code>org.freedesktop.ScreenSaver</code>)</td>
+    </tr>
+  </tbody>
+</table>
+
+<p style="margin-top:1em;">
+<sup>[1]</sup> The Linux support is under active development. Target is to support at least GNOME, KDE, Xfce, Cinnamon, LXQt and MATE Desktop Environments.<p>
 
-
-## Requirements
-
-Wakepy supports Windows, MacOS and Linux flavours which Desktop Environment that implements the `org.freedesktop.ScreenSaver` interface[^linux-support].
-
-[^linux-support]: The Linux support is under active development. Target is to support at least GNOME, KDE, Xfce, Cinnamon, LXQt and MATE Desktop Environments.
 ## Installing
 
-To install wakepy from PyPI, run
-
-```{code-block} text
-pip install wakepy
-```
-
-```{note}
-On Linux will install also **[`jeepney`](https://jeepney.readthedocs.io/)** for DBus communication (if not installed). On other systems there are no python requirements.
-
-On Python 3.7 installs [typing-extensions](https://pypi.org/project/typing-extensions/).
-```
-
-## Basic Usage
-
-If you want to keep a long task running, but do not want to prevent screen from locking and/or blanking, you can use `keep.running` context manager. If you also want to prevent screen lock and screen blank, use `keep.presenting`:
-
+Wakepy supports CPython 3.7 to 3.13, and may be installed with
 
-::::{tab-set}
-
-:::{tab-item} No screen required
-
-```{code-block} python
-from wakepy import keep
-
-with keep.running():
-    # Do something that takes a long time
 ```
-
-:::
-
-:::{tab-item} Screen required
-
-```{code-block} python
-from wakepy import keep
-
-with keep.presenting():
-    # Do something that takes a long time
+pip install wakepy
 ```
 
-:::
+## Why wakepy?
+Here's some reasons why you might want to consider using wakepy:
 
-::::
+🛡️ For security reasons
+: When you don't want to use a technique which keeps the screen awake and disables the automatic screen lock. I.e. you *only* want to disable the automatic suspend. 
 
+🦸 You need a cross-platform solution
+: Same code works on Windows, macOS and Linux.
 
-### Mode quick reference
+⚙️ You want to have more control
+: It is possible to whitelist or blacklist the used wakepy Methods. It is also possible to prioritize them and define a on-fail action in case activating a wakepy mode fails.
 
+✂️ You want to keep the amount of dependencies low
+: If you're running wakepy on Linux,  [jeepney](https://jeepney.readthedocs.io/) is required for D-Bus based methods. On Python 3.7,  [typing-extensions](https://pypi.org/project/typing-extensions/) is needed for typing. Otherwise: wakepy has no python dependencies.
 
+⚖️ Package needs to have a permissive licence
+: Wakepy is licenced under permissive [MIT License](https://github.com/fohrloop/wakepy/blob/main/LICENSE.txt).
 
-| Wakepy mode              | keep.running | keep.presenting |
-| ------------------------ | ------------ | --------------- |
-| Sleep is prevented       | Yes          | Yes             |
-| Screenlock is prevented  | No*          | Yes             |
-| Screensaver is prevented | No*          | Yes             |
+## Where wakepy is used?
 
-
-
-```{note}
-The table above only considers the *automatic* actions (go to sleep, start screenlock, start screensaver), which are based on the *idle timer*; 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 lock the session/screen or start screensaver.
-```
+- [viskillz-blender](https://github.com/viskillz/viskillz-blender) — Generating assets of Mental Cutting Test exercises
+- [mpc-autofill](https://github.com/chilli-axe/mpc-autofill) — Automating MakePlayingCards' online ordering system
+- [lakeshorecryotronics/python-driver](https://github.com/lakeshorecryotronics/python-driver) — Lake Shore instruments python Driver
+- [UCSD-E4E/baboon-tracking](https://github.com/UCSD-E4E/baboon-tracking) — In pipelines of a Computer Vision project tracking baboons
+- [davlee1972/upscale_video](https://github.com/davlee1972/upscale_video) — Upscaling video using AI
+- [minarca](https://github.com/ikus060/minarca) — Cross-platform data backup software
 
 
 
@@ -80,12 +97,24 @@ The table above only considers the *automatic* actions (go to sleep, start scree
 :numbered: -1
 :titlesonly:
 
+quickstart
+tutorial
+```
+
+```{toctree}
+:hidden:
+:caption: 'Reference Manual:'
+:maxdepth: 2
+:numbered: -1
+:titlesonly:
+
 modes
 methods-reference
 api-reference
 cli-api
 ```
 
+
 ```{toctree}
 :hidden:
 :caption: 'Advanced Usage:'

diff --git a/docs/source/modes.md b/docs/source/modes.md
@@ -2,11 +2,23 @@
 
 
 
+
+
 The available modes are
-| Wakepy mode                              | What it does                                        |
-| ---------------------------------------- | --------------------------------------------------- |
-| [keep.running](#keep-running-mode)       | Automatic sleep is prevented                        |
-| [keep.presenting](#keep-presenting-mode) | Automatic sleep, screensaver & screenlock prevented |
+
+| Wakepy mode              | [keep.running](#keep-running-mode) | [keep.presenting](#keep-presenting-mode)|
+| ------------------------ | ------------ | --------------- |
+| Sleep is prevented       | Yes          | Yes             |
+| Screenlock is prevented  | No[^win-slock]          | Yes             |
+| Screensaver is prevented | No          | Yes             |
+
+[^win-slock]: Depending on system settings, it is possible that Windows will not automatically lock the system, because Windows will lock the screen either when (1) returning from suspend (which is now inhibited) or (2) when returning from Screen Saver, *if ScreenSaverIsSecure is set or enforced by a Group Policy (GPO)*.  See: [wakepy/#169](https://github.com/fohrloop/wakepy/issues/169)
+
+```{note}
+The table above only considers the *automatic* actions (go to sleep, start screenlock, start screensaver), which are based on the *idle timer*; 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 lock the session/screen or start screensaver.
+```
+
+
 
 ## Entering a mode
 

diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md
@@ -0,0 +1,53 @@
+# Quickstart
+
+
+## Installing
+
+To install wakepy from PyPI, run
+
+```{code-block} text
+pip install wakepy
+```
+
+## Basic Usage
+
+### Long running tasks
+
+If you want to keep a long task running, but do not want to prevent screen from locking and/or blanking, you can use the [`keep.running`](#keep-running-mode) function which returns a context manager:
+
+
+```{code-block} python
+from wakepy import keep
+
+with keep.running():
+    # Do something that takes a long time. The system may start screensaver
+    # / screenlock, but CPU will keep running.
+```
+
+
+### Keeping screen awake
+If you want to prevent screen lock and screen blank *in addition to* keeping CPU awake, use the [`keep.presenting`](#keep-presenting-mode) function which returns a context manager:
+
+
+```{code-block} python
+from wakepy import keep
+
+with keep.presenting():
+    # Do something that takes a long time and requires the screen to be awake
+```
+
+
+
+```{admonition} Wakepy API is still experimental 🚧
+:class: note
+
+Since wakepy is still 0.x.x, the API might change without further notice from
+one release to another. After that, breaking changes should occur only part of
+a major release (e.g. 1.x.x -> 2.0.0). 
+```
+
+
+
+
+
+