Improve docs, add docs tests and remove vendored theme (#2890)

* Add doc tests, make them pass

* push.yml
   * Added documentation step which installs [docs], checks links and builds documentation to find any errors.
   * Need to install to get all the dependencies, because p4a code is imported during doc generation.
   * Updated rest of checkout action versions to be consistent with new code.

* apis.rst
   * http -> https
   * Disambiguated two modules with the same name.

* buildoptions.rst
   * Corrected indenting

* conf,py
   * Added language
   * Added two URLS to ignore that link-checker was failing even though they worked.

* ext/sphinix_rtd_theme/*
   * Old theme did not work with Sphinx 7.0+.
   * Removed it from source control. Install the latest each time.

* launcher.rst
   * This described an old feature that hasn't worked for years. Couldn't fix the links because the whole feature is gone now. Removed it. If the attempts to bring the feature back ever come to fruition, this can be restored and edited.

* index.rst
   * Removed no-longer-existing anchor,
   * Removed launcher page

* quickstart.rst
   * Removed launcher

* recipe.rst
   * Fixed syntax error in rst.

* services,rst
   * Fixed broken URL (and linked to project rather than bug-tracker.)

* troubleshooting.rst
   * http->https
   * Link to English rather than Chinese web-sites.

* setup.py
   * Add docs as extra.

* Updated with review comments.

* Fix broken links in documentation.

One dead link, causing test to fail.
Several permanent redirects where it is better to use the final destination.

The rest

Author: Julian-O

.github/workflows/push.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout python-for-android
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: Set up Python 3.x
       uses: actions/setup-python@v4
       with:
@@ -36,7 +36,7 @@ jobs:
         os: [ubuntu-latest, macOs-latest]
     steps:
     - name: Checkout python-for-android
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v4
       with:
@@ -72,7 +72,7 @@ jobs:
             target: testapps-service_library-aar
     steps:
     - name: Checkout python-for-android
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: Build python-for-android docker image
       run: |
         docker build --tag=kivy/python-for-android .
@@ -121,7 +121,7 @@ jobs:
       ANDROID_NDK_HOME: ${HOME}/.android/android-ndk
     steps:
       - name: Checkout python-for-android
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Install python-for-android
         run: |
           source ci/osx_ci.sh
@@ -170,7 +170,7 @@ jobs:
       REBUILD_UPDATED_RECIPES_EXTRA_ARGS: --arch=${{ matrix.android_arch }}
     steps:
     - name: Checkout python-for-android (all-history)
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0
     # helps with GitHub runner getting out of space
@@ -206,7 +206,7 @@ jobs:
       REBUILD_UPDATED_RECIPES_EXTRA_ARGS: --arch=${{ matrix.android_arch }}
     steps:
       - name: Checkout python-for-android (all-history)
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Install python-for-android
@@ -238,3 +238,15 @@ jobs:
       uses: AndreMiras/coveralls-python-action@develop
       with:
         parallel-finished: true
+
+  documentation:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Requirements
+      run: python3 -m pip install .[docs]
+    - name: Check links
+      run: sphinx-build -b linkcheck doc/source doc/build
+    - name: Generate documentation
+      run: sphinx-build doc/source doc/build
+

doc/source/apis.rst

@@ -48,7 +48,7 @@ Requires `Permission.WRITE_EXTERNAL_STORAGE` to read and write to.
 Read more on all the different storage types and what to use them for
 in the Android documentation:
 
-https://developer.android.com/training/data-storage/files
+https://developer.android.com/training/data-storage
 
 A note on permissions
 ~~~~~~~~~~~~~~~~~~~~~
@@ -148,7 +148,7 @@ Observing Activity result
 
 .. module:: android.activity
 
-The default PythonActivity has a observer pattern for `onActivityResult <http://developer.android.com/reference/android/app/Activity.html#onActivityResult(int, int, android.content.Intent)>`_ and `onNewIntent <http://developer.android.com/reference/android/app/Activity.html#onNewIntent(android.content.Intent)>`_.
+The default PythonActivity has a observer pattern for `onActivityResult <https://developer.android.com/reference/android/app/Activity#onActivityResult(int, int, android.content.Intent)>`_ and `onNewIntent <https://developer.android.com/reference/android/app/Activity.html#onNewIntent(android.content.Intent)>`_.
 
 .. function:: bind(eventname=callback, ...)
 
@@ -193,8 +193,6 @@ Example::
 Activity lifecycle handling
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. module:: android.activity
-
 The Android ``Application`` class provides the `ActivityLifecycleCallbacks
 <https://developer.android.com/reference/android/app/Application.ActivityLifecycleCallbacks>`_
 interface where callbacks can be registered corresponding to `activity
@@ -241,7 +239,7 @@ Receiving Broadcast message
 .. module:: android.broadcast
 
 Implementation of the android `BroadcastReceiver
-<http://developer.android.com/reference/android/content/BroadcastReceiver.html>`_.
+<https://developer.android.com/reference/android/content/BroadcastReceiver.html>`_.
 You can specify the callback that will receive the broadcast event, and actions
 or categories filters.
 
@@ -308,7 +306,7 @@ Runnable
 .. module:: android.runnable
 
 :class:`Runnable` is a wrapper around the Java `Runnable
-<http://developer.android.com/reference/java/lang/Runnable.html>`_ class. This
+<https://developer.android.com/reference/java/lang/Runnable.html>`_ class. This
 class can be used to schedule a call of a Python function into the
 `PythonActivity` thread.
 
@@ -443,5 +441,5 @@ sometimes a little more involved, particularly if making Java classes
 from Python code), but it's not Pythonic and it's not short. These are
 problems that Plyer, explained below, attempts to address.
 
-You can check the `Pyjnius documentation <https://pyjnius.readthedocs.io/en/stable/>`_ for further details.
+You can check the `Pyjnius documentation <https://pyjnius.readthedocs.io/en/latest/>`_ for further details.
 

doc/source/buildoptions.rst

@@ -62,7 +62,7 @@ options (this list may not be exhaustive):
   Since Android ignores ``android:screenOrientation`` when in multi-window mode
   (Which is the default on Android 12+), this option will also set the window orientation hints
   for the SDL bootstrap. If multiple orientations are given,
-``android:screenOrientation`` will be set to ``unspecified``.
+  ``android:screenOrientation`` will be set to ``unspecified``.
 - ``--manifest-orientation``: The orientation that will be set for the ``android:screenOrientation``
   attribute of the activity in the ``AndroidManifest.xml`` file. If not set, the value 
   will be synthesized from the ``--orientation`` option.

doc/source/conf.py

@@ -72,7 +72,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -293,4 +293,14 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping =  {'python': ('https://docs.python.org/3', None)}
+
+# Ignore some troublesome links that are actually fine.
+linkcheck_ignore = [
+    # Special characters in URL seems to confuse link-checker.
+    r"https://developer.android.com/reference/android/app/Activity#onActivity.*",
+
+    # GitHub parses anchor tags differently to pure HTML
+    r"https://github.com/kivy/python-for-android/blob.*",
+    ]
+