Update RTD documentation with recent developments

RTD configuration file and a default index.rst is now required and
some Sphinx settings have also changed accordingly. Let us also use
the opportunity to simplify the API doc generation bash script.

.readthedocs.yaml

@@ -0,0 +1,29 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the docs/api directory with Sphinx
+sphinx:
+  builder: html
+  configuration: docs/api/conf.py
+  fail_on_warning: true
+
+# Build docs in additional formats such as PDF and ePub
+formats: all
+
+# Specify dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: packaging/pip_requirements_minimal.txt
+    - method: pip
+      path: ./packaging/

docs/api/conf.py

@@ -82,7 +82,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:

docs/api/generate_api.sh

@@ -1,17 +1,18 @@
 #!/bin/bash
+# Run this script when producing new documentation to submit to RTD.
+
+set -e
 
 # produce rst files for the modules
 sphinx-apidoc -e -f -o . ../../guibot || die "No rst files could be generated"
 
 # move all rst files to source directory to integrate with RTD
-mv README.rst README.rst.bak
-rm -fr source README.rst
+rm -fr source index.rst
 mkdir source || die "No source directory to move rst files to"
 mv *.rst source
 
 # produce HTML documentation from the rst files
 make html
 
 # use README as index page for RTD (needs MD-RST compatibility)
-# pandoc ../../README.md --from markdown --to rst -s -o README.rst
-mv README.rst.bak README.rst
+pandoc ../../README.md --from markdown --to rst -s -o index.rst

docs/api/index.rst

@@ -0,0 +1,98 @@
+Guibot |GH Actions| |Documentation Status| |CodeQL| |codecov|
+=============================================================
+
+A tool for GUI automation using a variety of computer vision and display
+control backends.
+
+Introduction and concepts
+-------------------------
+
+In order to do GUI automation you usually need to solve two problems:
+first, you need to have a way to control and interact with the interface
+and platform you are automating and second, you need to be able to
+locate the objects you are interested in on the screen. Guibot helps you
+do both.
+
+To interact with GUIs, Guibot provides the
+```controller`` <https://github.com/intra2net/guibot/blob/master/guibot/controller.py>`__
+module which contains a common interface for different display backends,
+with methods to move the mouse, take screenshots, type characters and so
+on. The backend to use will depend on how your platform is accessible,
+with some backends running directly as native binaries or python scripts
+on Windows, macOS, and Linux while others connecting through remote VNC
+displays.
+
+To locate an element on the screen, you will need an image representing
+the screen, a
+```target`` <https://github.com/intra2net/guibot/blob/master/guibot/target.py>`__
+representing the element (an image or a text in the simplest cases) and
+a
+```finder`` <https://github.com/intra2net/guibot/blob/master/guibot/finder.py>`__
+configured for the target. The finder looks for the target within the
+screenshot image and returns the coordinates to the region where that
+target appears. Finders, just like display controllers, are wrappers
+around different backends supported by Guibot that could vary from a
+simplest 1:1 pixel matching by controller backends, to template or
+feature matching mix by OpenCV, to OCR and ML solutions by Tesseract and
+AI frameworks.
+
+Finally, to bridge the gap between controlling the GUI and finding
+target elements, the
+```region`` <https://github.com/intra2net/guibot/blob/master/guibot/region.py>`__
+module is provided. It represents a subregion of a screen and contains
+methods to locate targets in this region using a choice of finder and
+interact with the graphical interface using a choice of controller.
+
+Supported backends
+------------------
+
+Supported Computer Vision (CV) backends are based on
+
+-  `OpenCV <https://github.com/opencv/opencv>`__
+
+   -  Template matching
+   -  Contour matching
+   -  Feature matching
+   -  Haar cascade matching
+   -  Template-feature and mixed matching
+
+-  `Tesseract OCR <https://github.com/tesseract-ocr/tesseract>`__
+
+   -  Text matching through pytesseract, tesserocr, or OpenCV’s bindings
+
+-  `PyTorch <https://github.com/pytorch/pytorch>`__
+
+   -  R-CNN matching through Faster R-CNN or Mask R-CNN
+
+-  `autopy <https://github.com/msanders/autopy>`__
+
+   -  AutoPy matching
+
+Supported Display Controller (DC) backends are based on
+
+-  `PyAutoGUI <https://github.com/asweigart/pyautogui>`__
+-  `AutoPy <https://github.com/msanders/autopy>`__
+-  `VNCDoTool <https://github.com/sibson/vncdotool>`__
+-  `XDoTool <https://www.semicomplete.com/projects/xdotool>`__
+
+Further resources
+-----------------
+
+Homepage: http://guibot.org
+
+Documentation: http://guibot.readthedocs.io
+
+Installation: https://github.com/intra2net/guibot/wiki/Packaging
+
+Issue tracking: https://github.com/intra2net/guibot/issues
+
+Project wiki: https://github.com/intra2net/guibot/wiki
+
+.. |GH Actions| image:: https://github.com/intra2net/guibot/actions/workflows/ci.yml/badge.svg
+   :target: https://github.com/intra2net/guibot/actions/workflows/ci.yml
+.. |Documentation Status| image:: https://readthedocs.org/projects/guibot/badge/?version=latest
+   :target: http://guibot.readthedocs.io/en/latest/?badge=latest
+.. |CodeQL| image:: https://github.com/intra2net/guibot/actions/workflows/codeql.yml/badge.svg
+   :target: https://github.com/intra2net/guibot/actions/workflows/codeql.yml
+.. |codecov| image:: https://codecov.io/gh/intra2net/guibot/branch/master/graph/badge.svg
+   :target: https://codecov.io/gh/intra2net/guibot

docs/api/source/guibot.calibrator.rst

@@ -2,6 +2,6 @@ guibot.calibrator module
 ========================
 
 .. automodule:: guibot.calibrator
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/source/guibot.config.rst

@@ -2,6 +2,6 @@ guibot.config module
 ====================
 
 .. automodule:: guibot.config
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/source/guibot.controller.rst

@@ -2,6 +2,6 @@ guibot.controller module
 ========================
 
 .. automodule:: guibot.controller
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/source/guibot.desktopcontrol.rst

@@ -2,6 +2,6 @@ guibot.desktopcontrol module
 ============================
 
 .. automodule:: guibot.desktopcontrol
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/source/guibot.errors.rst

@@ -2,6 +2,6 @@ guibot.errors module
 ====================
 
 .. automodule:: guibot.errors
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/source/guibot.fileresolver.rst

@@ -2,6 +2,6 @@ guibot.fileresolver module
 ==========================
 
 .. automodule:: guibot.fileresolver
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/source/guibot.finder.rst

@@ -2,6 +2,6 @@ guibot.finder module
 ====================
 
 .. automodule:: guibot.finder
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/source/guibot.guibot.rst

@@ -2,6 +2,6 @@ guibot.guibot module
 ====================
 
 .. automodule:: guibot.guibot
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/source/guibot.guibot_proxy.rst

@@ -2,6 +2,6 @@ guibot.guibot\_proxy module
 ===========================
 
 .. automodule:: guibot.guibot_proxy
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/source/guibot.guibot_simple.rst

@@ -2,6 +2,6 @@ guibot.guibot\_simple module
 ============================
 
 .. automodule:: guibot.guibot_simple
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/source/guibot.imagelogger.rst

@@ -2,6 +2,6 @@ guibot.imagelogger module
 =========================
 
 .. automodule:: guibot.imagelogger
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance: