Add (now mandatory) .readthedocs.yaml file, add docs requirements.txt and update sphinx conf (kivy#2916)

misl6 · web-flow · commit 609ad2d61c24 · 2023-11-10T20:52:22.000+01:00
* Add (now mandatory) .readthedocs.yaml file, add docs requirements.txt and update sphinx conf

* Do not use a double source of truth for docs dependencies. extra_require is great, but unfortunately we can't use it on readthedocs builds
diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml
@@ -244,7 +244,9 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Requirements
-      run: python3 -m pip install .[docs]
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r doc/requirements.txt
     - name: Check links
       run: sphinx-build -b linkcheck doc/source doc/build
     - name: Generate documentation
diff --git a/.readthedocs.yaml 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: doc/requirements.txt
+
+sphinx:
+  configuration: doc/source/conf.py
diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -0,0 +1,2 @@
+Sphinx~=7.2.6
+furo==2023.9.10
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -12,19 +12,17 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
+import datetime
 import os
-import shlex
+import re
+import sys
 
 # 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.
 #sys.path.insert(0, os.path.abspath('.'))
-sys.path.append(os.path.abspath('ext/sphinx_rtd_theme'))
 sys.path.append(os.path.abspath('../../pythonforandroid'))
 
-import sphinx_rtd_theme
-
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -54,18 +52,35 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'python-for-android'
-copyright = u'2015, Alexander Taylor'
-author = u'Alexander Taylor'
+project = 'python-for-android'
+
+_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("../.."), "pythonforandroid", "__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 = '0.1'
+version = get_version()
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = get_version()
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -82,7 +97,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['ext/*', ]
+exclude_patterns = []
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -116,15 +131,15 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+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
 # documentation.
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+# html_theme_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -230,8 +245,8 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  (master_doc, 'python-for-android.tex', u'python-for-android Documentation',
-   u'Alexander Taylor', 'manual'),
+  (master_doc, 'python-for-android.tex', 'python-for-android Documentation',
+   author, 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
diff --git a/setup.py b/setup.py
@@ -95,9 +95,6 @@ def recursively_include(results, directory, patterns):
       url='https://github.com/kivy/python-for-android',
       license='MIT',
       install_requires=install_reqs,
-      extras_require={
-          "docs": ["sphinx", "sphinx-rtd-theme"],
-      },
       entry_points={
           'console_scripts': [
               'python-for-android = pythonforandroid.entrypoints:main',
