From 1e8a38c501b061e307297954eb6aff6a886a2992 Mon Sep 17 00:00:00 2001 From: Mirko Galimberti Date: Fri, 10 Nov 2023 12:41:46 +0100 Subject: [PATCH 1/2] Add (now mandatory) .readthedocs.yaml file, add docs requirements.txt and update sphinx conf --- .readthedocs.yaml | 16 ++++++++++++++++ doc/requirements.txt | 2 ++ doc/source/conf.py | 45 +++++++++++++++++++++++++++++--------------- 3 files changed, 48 insertions(+), 15 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 doc/requirements.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..e3f99e76b0 --- /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: doc/requirements.txt + +sphinx: + configuration: doc/source/conf.py \ No newline at end of file diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000000..2a72e68703 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,2 @@ +Sphinx~=7.2.6 +furo==2023.9.10 \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index e4ea304fde..a355505748 100644 --- 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,7 +131,7 @@ # 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 @@ -124,7 +139,7 @@ #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 # " v 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 From d92e1f938ab1eacad3e9b2323886a0ba3b397f79 Mon Sep 17 00:00:00 2001 From: Mirko Galimberti Date: Fri, 10 Nov 2023 14:32:31 +0100 Subject: [PATCH 2/2] 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 --- .github/workflows/push.yml | 4 +++- setup.py | 3 --- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml index 7b79a30a63..d7f789aaaf 100644 --- 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/setup.py b/setup.py index 8099647a93..6351cdcf8a 100644 --- 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',