Update doc pages appearance & README (#193)

Update docs
-----------
* Start using new theme: sphinx-book-theme
* customize the theme
* Make the Quickstart page to be the docs landing page
  (this is a bit of a hack but anyway)
* Flatten the docs structure 

Update readme
-------------
* jeepney is still a required dependency

Author: fohrloop

README.md

@@ -3,10 +3,7 @@
 
 # ⏰😴 wakepy 
 
- Cross-platform wakelock written in Python. 
- - It has zero required python dependencies.
- - Python API for application and library developers, and a wakepy executable (CLI) for everyone.
-
+Cross-platform wakelock / keep-awake / stay-awake written in Python. 
 
 ## Supports
 - Python: 3.7 to 3.12 
@@ -15,7 +12,7 @@
 ## What it can do? 
 
 Wakepy has two main modes:
-1. **`keep.running`**: keep your tasks & CPU running even if you lock your session and turn screenlock on; This mode prevents your system from going to sleep (*e.g.* for training machine learning models, video encoding, web scraping, ...)
+1. **`keep.running`**: keep your tasks & CPU running even if you lock your session and turn screenlock on; This mode prevents your system from going to sleep automatically (*e.g.* for training machine learning models, video encoding, web scraping, ...)
 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 -->
 
@@ -32,11 +29,12 @@ Wakepy has two main modes:
 ### 👉 **[wakepy.readthedocs.io](http://wakepy.readthedocs.io)**
 <!-- start after docs link -->
 ## ⚖️👑 Key selling points
-- Wakepy supports multiple operating systems and desktop environments
-- Wakepy has permissive MIT licence
-- It has a simple command line interface and a python API
-- Wakepy has zero required python dependencies
-  - For using the D-Bus methods on Linux, one may use [jeepney](https://jeepney.readthedocs.io/) (optional)
+- Supports multiple operating systems and desktop environments
+- Simple command line interface and a python API
+- Permissive MIT licence
+- Low amount of python dependencies
+  - For using the D-Bus methods on Linux: [jeepney](https://jeepney.readthedocs.io/)  
+  - Otherwise: None
 
 
 ## Deprecation timeline (wakepy 0.7.0+) 

docs/source/_templates/author.html

@@ -0,0 +1,33 @@
+{#
+Most of the contents of this file are copied from the sphinx-book-theme
+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.
+    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>
+    <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 #}
+        <ul class="nav bd-sidenav bd-sidenav__home-link">
+            <li class="toctree-l1{% if pagename == root_doc %} current active{% endif %}">
+                <a class="reference internal" href="{{ pathto(root_doc) }}">
+                    {{ root_title }}
+                </a>
+            </li>
+        </ul>
+        {% endif -%}
+        {# Ref:
+        https://github.com/pydata/pydata-sphinx-theme/blob/ebf7f704879a1cdc6016d6111062103353ac7677/src/pydata_sphinx_theme/__init__.py#L302
+        #}
+        {{- generate_toctree_html(
+        startdepth=0,
+        kind="sidebar",
+        maxdepth=theme_max_navbar_depth|int,
+        collapse=theme_collapse_navbar|tobool,
+        includehidden=True,
+        titles_only=True,
+        show_nav_level=theme_show_navbar_depth|int) }}
+    </div>
+</nav>

docs/source/_templates/sbt-sidebar-nav.html

@@ -1,17 +1,20 @@
 # CLI API
 
 It is possibe to start wakepy from the command line either by running
-```
+
+```{code-block} text
 wakepy 
 ```
+
 or  
-```
+
+```{code-block} text
 python -m wakepy
 ```
 
 This starts wakepy in the *default mode* (`-k`), which corresponds to a call to `keep.running` with default arguments. The available options are:
 
-```
+```{code-block} output
 wakepy [-h] [-k] [-p]
 
 options:

docs/source/cli-api.md

@@ -9,7 +9,7 @@
 from wakepy import __version__
 
 project = "wakepy"
-copyright = "2023, Niko Föhr"
+copyright = "2023–2024, Niko Föhr"
 author = "Niko Föhr"
 
 # The full version, including alpha/beta/rc tags
@@ -82,19 +82,16 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "furo"
-
+html_theme = "sphinx_book_theme"
+html_title = f"wakepy {__version__}"
 html_theme_options = {
-    "footer_icons": [
-        {
-            "name": "GitHub",
-            "url": "https://github.com/fohrloop/wakepy",
-            "html": """
-                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
-                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
-                </svg>
-            """,  # noqa E501
-            "class": "",
-        },
-    ],
+    "repository_url": "https://github.com/fohrloop/wakepy",
+    "use_repository_button": True,
+    "use_download_button": False,
+    "use_fullscreen_button": False,
+    # Shows the landing page in the sidebar
+    # See: https://sphinx-book-theme.readthedocs.io/en/stable/sections/sidebar-primary.html#add-the-home-page-to-your-table-of-contents
+    "home_page_in_toc": True,
+    "pygment_light_style": "friendly",
+    "pygment_dark_style": "lightbulb",
 }

docs/source/conf.py

@@ -1,30 +1,114 @@
-```{include} ../../README.md
-:start-after: <!-- start before docs link -->
-:end-before:  <!-- end before docs link -->
+# Quickstart
+
+
+## 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.
+```
+
+## 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`:
+
+
+::::{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
 ```
-```{include} ../../README.md
-:start-after: <!-- start after docs link -->
-:end-before:  <!-- end after docs link -->
+
+:::
+
+::::
+
+
+### Mode quick reference 
+ 
+
+
+| Wakepy mode              | keep.running | keep.presenting |
+| ------------------------ | ------------ | --------------- |
+| Sleep is prevented       | Yes          | Yes             |
+| Screenlock is prevented  | No*          | Yes             |
+| Screensaver is prevented | No*          | Yes             |
+
+
+
+```{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.
 ```
 
+
+
 ## Links
 - GitHub: [github.com/fohrloop/wakepy](https://github.com/fohrloop/wakepy)
 - PyPI: [pypi.org/project/wakepy](https://pypi.org/project/wakepy/)
 
-## Documentation TOC
 ```{toctree}
-:caption: 'Contents:'
+:hidden:
 :maxdepth: 2
 :numbered: -1
 :titlesonly:
 
-user-guide/index
+quickstart
+modes
 methods-reference
-technical-details/index
+
 cli-api
 ```
 
 ```{toctree}
+:hidden:
+:caption: 'Advanced Usage:'
+:maxdepth: 2
+:numbered: -1
+:titlesonly:
+
+tests-and-ci
+```
+
+
+```{toctree}
+:hidden:
+:caption: 'Technical Details:'
+:maxdepth: 2
+:numbered: -1
+:titlesonly:
+
+wakepy-mode-lifecycle
+test-manually
+```
+
+```{toctree}
+:hidden:
 :caption: 'Development:'
 :maxdepth: 2
 :numbered: -1