Modify docs (#1922)

* Add sphinxawesome_theme dependency for docs

* Update configuration for docs

* upload images for logo and banner

* Basic modifications for current theme

* Update conf.py

* Update test_python.yml

Author: Novfensec

.github/workflows/test_python.yml

@@ -68,7 +68,7 @@ jobs:
     steps:
     - uses: actions/checkout@v5
     - name: Requirements
-      run: pip install --upgrade sphinx
+      run: pip install -U sphinx sphinxawesome_theme
     - name: Check links
       run: sphinx-build -b linkcheck docs/source docs/build
     - name: Generate documentation

docs/source/_static/images/banner.svg

@@ -14,6 +14,8 @@
 import os
 import re
 
+from sphinxawesome_theme.postprocess import Icons
+
 # 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.
@@ -42,7 +44,7 @@
 
 # General information about the project.
 project = u'Buildozer'
-copyright = u'2014-2023, Kivy Team and other contributors'
+copyright = u'2014-2025, Kivy Team and other contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -97,6 +99,7 @@ def get_version():
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
+pygments_style_dark = 'dracula'
 
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
@@ -109,12 +112,49 @@ def get_version():
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'sphinxawesome_theme'
+
+# Customized permalinks icon
+html_permalinks_icon = Icons.permalinks_icon
 
 # 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 = {}
+html_theme_options = {
+    "logo_light": "_static/images/logo.png",
+    "logo_dark": "_static/images/logo_dark.png",
+    "awesome_external_links": True,
+    "show_prev_next": True,
+    "extra_header_link_icons": {
+        "GitHub": {
+            "link": "https://github.com/Kivy/Buildozer",
+            "icon": (
+                '<svg height="26px" style="margin-top:-2px;display:inline" '
+                'viewBox="0 0 45 44" '
+                'fill="currentColor" xmlns="http://www.w3.org/2000/svg">'
+                '<path fill-rule="evenodd" clip-rule="evenodd" '
+                'd="M22.477.927C10.485.927.76 10.65.76 22.647c0 9.596 6.223 17.736 '
+                "14.853 20.608 1.087.2 1.483-.47 1.483-1.047 "
+                "0-.516-.019-1.881-.03-3.693-6.04 "
+                "1.312-7.315-2.912-7.315-2.912-.988-2.51-2.412-3.178-2.412-3.178-1.972-1.346.149-1.32.149-1.32 "  # noqa
+                "2.18.154 3.327 2.24 3.327 2.24 1.937 3.318 5.084 2.36 6.321 "
+                "1.803.197-1.403.759-2.36 "
+                "1.379-2.903-4.823-.548-9.894-2.412-9.894-10.734 "
+                "0-2.37.847-4.31 2.236-5.828-.224-.55-.969-2.759.214-5.748 0 0 "
+                "1.822-.584 5.972 2.226 "
+                "1.732-.482 3.59-.722 5.437-.732 1.845.01 3.703.25 5.437.732 "
+                "4.147-2.81 5.967-2.226 "
+                "5.967-2.226 1.185 2.99.44 5.198.217 5.748 1.392 1.517 2.232 3.457 "
+                "2.232 5.828 0 "
+                "8.344-5.078 10.18-9.916 10.717.779.67 1.474 1.996 1.474 4.021 0 "
+                "2.904-.027 5.247-.027 "
+                "5.96 0 .58.392 1.256 1.493 1.044C37.981 40.375 44.2 32.24 44.2 "
+                '22.647c0-11.996-9.726-21.72-21.722-21.72" '
+                'fill="currentColor"/></svg>'
+            ),
+        },
+    },
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
@@ -133,12 +173,12 @@ def get_version():
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-#html_favicon = None
+html_favicon = "_static/images/logo.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

docs/source/_static/images/logo.png

@@ -1,3 +1,5 @@
+.. _faq:
+
 FAQ
 ===
 

docs/source/_static/images/logo_dark.png

@@ -1,11 +1,25 @@
+.. _introduction:
+
 Welcome to Buildozer's documentation!
 =====================================
 
+.. rst-class:: lead
+
+   Generic Python packager for Android and iOS.
+
+Overview
+--------
+
+.. figure:: /_static/images/banner.svg
+   :alt: Buildozer
+   :height: 300px
+   :align: center
+
 Buildozer is a development tool for turning Python
 applications into binary packages ready for installation on any of a number of
 platforms, including mobile devices. It automates the entire build process.
 
-The app developer provides a single "buildozer.spec" file, which describes the
+The app developer provides a single :class:`buildozer.spec` file, which describes the
 application's requirements and settings, such as title and icons. Buildozer can
 then create installable packages for Android, iOS, Windows, macOS and/or Linux.
 
@@ -14,16 +28,16 @@ building apps using the `Kivy framework <https://kivy.org/doc/stable/>`_ easier,
 but it can be used independently - even with other GUI frameworks.
 
 .. note::
-   python-for-android only runs on Linux or macOS. (On Windows, a Linux emulator is
+   python-for-android toolchain only runs on Linux or macOS. (On Windows, a Linux emulator is
    required.)
 
-   Kivy for iOS only runs on macOS.
+   kivy-ios toolchain only runs on macOS.
 
 Buildozer is managed by the `Kivy Team <https://kivy.org/about.html>`_. It relies
 on its sibling projects:
-`python-for-android <https://python-for-android.readthedocs.io/en/latest/>`_ for
+`python-for-android toolchain <https://python-for-android.readthedocs.io/en/latest/>`_ for
 Android packaging, and
-`Kivy for iOS <https://github.com/kivy/kivy-ios/>`_ for iOS packaging.
+`kivy-ios toolchain <https://github.com/kivy/kivy-ios/>`_ for iOS packaging.
 
 Buildozer is released and distributed under the terms of the MIT license. You should have received a
 copy of the MIT license alongside your distribution. Our
@@ -32,10 +46,16 @@ is also available.
 
 
 .. note::
-   This tool is unrelated to the online build service, `buildozer.io`.
+   This tool is has no relation to the online build service, `buildozer.io`.
+
+
+.. toctree::
+   :hidden:
+
+   Introduction <self>
 
 .. toctree::
-   :maxdepth: 2
+   :hidden:
 
    installation
    quickstart

docs/source/conf.py

@@ -1,3 +1,5 @@
+.. _installation:
+
 Installation
 ============
 
@@ -91,7 +93,7 @@ you can install just the platform tools which also contain ADB.
 - Visit the `Android SDK Platform Tools <https://developer.android.com/tools/releases/platform-tools>`_ page, and
   select "Download SDK Platform-Tools for Windows".
 
-- Unzip the downloaded file to a new folder. For example, `C:\\platform-tools\\`
+- Unzip the downloaded file to a new folder. For example, :class:`C:\\platform-tools\\`
 
 
 Install on macOS

docs/source/faq.rst

@@ -1,22 +1,26 @@
+.. _quickstart:
+
 Quickstart
 ==========
 
-Let's get started with Buildozer!
+.. rst-class:: lead
+
+   Let's get started with Buildozer!
 
 Init and build for Android
 --------------------------
 
 #. Buildozer will try to guess the version of your application, by searching a
-   line like `__version__ = "1.0.3"` in your `main.py`. Ensure you have one at
+   line like :class:`__version__ = "1.0.3"` in your :class:`main.py`. Ensure you have one at
    the start of your application. It is not mandatory but heavily advised.
 
-#. Create a `buildozer.spec` file, with::
+#. Create a :class:`buildozer.spec` file, with::
 
     buildozer init
 
-#. Edit the `buildozer.spec` according to the :ref:`specifications`. You should
-   at least change the `title`, `package.name` and `package.domain` in the
-   `[app]` section.
+#. Edit the :class:`buildozer.spec` according to the :ref:`specifications`. You should
+   at least change the :class:`title`, :class:`package.name` and :class:`package.domain` in the
+   :class:`[app]` section.
 
 #. Start an Android/debug build with::
 
@@ -28,7 +32,7 @@ Init and build for Android
    Don't worry, those files will be saved in a global directory and will be
    shared across the different projects you'll manage with Buildozer.
 
-#. At the end, you should have an APK or AAB file in the `bin/` directory.
+#. At the end, you should have an APK or AAB file in the :class:`bin/` directory.
 
 
 Run my application
@@ -40,29 +44,26 @@ your application at least once::
 
     buildozer android deploy run logcat
 
-For iOS, it would look the same::
+- For iOS, it would look the same::
 
     buildozer ios deploy run
 
-You can combine the compilation with the deployment::
+- You can combine the compilation with the deployment::
 
     buildozer -v android debug deploy run logcat
 
-You can also set this line at the default command to do if Buildozer is started
-without any arguments::
+- You can also set this line at the default command to do if Buildozer is started without any arguments::
 
     buildozer setdefault android debug deploy run logcat
     
     # now just type buildozer, and it will do the default command
     buildozer
 
-To save the logcat output into a file named `my_log.txt` (the file will appear in your current directory)::
+- To save the logcat output into a file named :class:`my_log.txt` (the file will appear in your current directory)::
 
     buildozer -v android debug deploy run logcat > my_log.txt
     
-To see your running application's print() messages and python's error messages, use:
-
-::
+- To see your running application's print() messages and python's error messages, use::
 
     buildozer -v android deploy run logcat | grep python
 
@@ -71,21 +72,16 @@ Run my application from Windows
 
 - Plug your Android device on a USB port.
 
-- Open Windows PowerShell, go into the folder where you installed the Windows version of ADB, and activate the ADB daemon. When the daemon is started you must see a number besides the word "device" meaning your device was correctly detected. In case of trouble, try another USB port or USB cable.
-
-::
+- Open Windows PowerShell, go into the folder where you installed the Windows version of ADB, and activate the ADB daemon. When the daemon is started you must see a number besides the word "device" meaning your device was correctly detected. In case of trouble, try another USB port or USB cable.::
 
     cd C:\platform-tools\
     .\adb.exe devices
 
-- Open the Linux distribution you installed on Windows Subsystem for Linux (WSL) and proceed with the deploy commands:
-
-::
+- Open the Linux distribution you installed on Windows Subsystem for Linux (WSL) and proceed with the deploy commands::
 
     buildozer -v android deploy run
     
-It is important to notice that Windows ADB and Buildozer-installed ADB must be the same version. To check the versions,
-open PowerShell and type::
+- It is important to notice that Windows ADB and Buildozer-installed ADB must be the same version. To check the versions, open PowerShell and type::
 
     cd C:\platform-tools\
     .\adb.exe version
@@ -97,8 +93,8 @@ Install on non-connected devices
 --------------------------------
 
 If you have compiled a package, and want to share it easily with others
-devices, you might be interested with the `serve` command. It will serve the
-`bin/` directory over HTTP. Then you just have to access to the URL showed in
+devices, you might be interested with the :class:`serve` command. It will serve the
+:class:`bin/` directory over HTTP. Then you just have to access to the URL showed in
 the console from your mobile::
 
     buildozer serve

docs/source/index.rst

@@ -1,6 +1,15 @@
+.. _recipes:
+
 Recipes
 =======
 
+..rst-class: lead
+
+    Compiling our python packages.
+
+Overview
+--------
+
 Python apps may depend on third party packages and extensions.
 
 Most packages are written in pure Python, and Buildozer can generally used them