From d16addd9d950105da664c4c5963d3d922cd5263b Mon Sep 17 00:00:00 2001
From: Mirko Galimberti <me@mirkogalimberti.com>
Date: Fri, 8 Dec 2023 10:01:17 +0100
Subject: [PATCH] Add (now mandatory) `.readthedocs.yaml` file, add docs extras
 and update sphinx conf (#787)

---
 .readthedocs.yaml     | 16 ++++++++++++++++
 docs/requirements.txt |  2 ++
 docs/source/conf.py   | 37 ++++++++++++++++++++++++++++---------
 3 files changed, 46 insertions(+), 9 deletions(-)
 create mode 100644 .readthedocs.yaml
 create mode 100644 docs/requirements.txt

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 00000000..1aed295c
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,16 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/source/conf.py
\ No newline at end of file
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 00000000..2a72e687
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,2 @@
+Sphinx~=7.2.6
+furo==2023.9.10
\ No newline at end of file
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 68248b87..f898c84c 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -11,9 +11,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import datetime
 import os
+import re
 import sys
-import plyer
 
 # 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
@@ -42,17 +43,35 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'Plyer'
-copyright = u'2013-2023, Kivy Team and other contributors'
+project = 'Plyer'
+
+_today = datetime.datetime.now()
+
+author = "Kivy Team and other contributors"
+
+copyright = f'{_today.year}, {author}'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
+
+# Lookup the version from the pyjnius module, without installing it
+# since readthedocs.org may have issue to install it.
+# Read the version from the __init__.py file, without importing it.
+def get_version():
+    with open(
+        os.path.join(os.path.abspath("../.."), "plyer", "__init__.py")
+    ) as fp:
+        for line in fp:
+            m = re.search(r'^\s*__version__\s*=\s*([\'"])([^\'"]+)\1\s*$', line)
+            if m:
+                return m.group(2)
+
 # The short X.Y version.
-version = plyer.__version__
+version = get_version()
 # The full version, including alpha/beta/rc tags.
-release = plyer.__version__
+release = get_version()
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -96,7 +115,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 = 'furo'
 
 # 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
@@ -189,7 +208,7 @@
 # (source start file, target name, title, author, documentclass [howto/manual])
 latex_documents = [(
     'index', 'Plyer.tex', u'Plyer Documentation',
-    u'Kivy Team and other contributors', 'manual'
+    author, 'manual'
 ), ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -219,7 +238,7 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('index', 'plyer', u'Plyer Documentation',
-     [u'Kivy Team and other contributors'], 1)
+     [author], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -233,7 +252,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [(
     'index', 'Plyer', u'Plyer Documentation',
-    u'Kivy Team and other contributors',
+    author,
     'Plyer',
     'Plyer is a platform-independent Python API for accessing hardware '
     'features of various platforms (Android, iOS, macOS, Linux and Windows).',