Add stup of the Sphinx internal docs

.gitignore

@@ -1,9 +1,11 @@
+
 **/*.zip
 **/*.img
 **/wpa_supplicant.conf
 zanzocam/web_ui/static/previews/*
 zanzocam/data/*
-!zanzocam/data/overlays/fallback-pixel.png
+
+**/build/*.*
 
 
 # Byte-compiled / optimized / DLL files

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/conf.py

@@ -0,0 +1,58 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'zanzocam-core'
+copyright = '2021, Sara Zanzottera'
+author = 'Sara Zanzottera'
+
+# The full version, including alpha/beta/rc tags
+release = '0.10.2'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.coverage',
+    'sphinx.ext.napoleon',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# 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']

docs/source/index.rst

@@ -0,0 +1,16 @@
+zanzocam-core documentation
+===========================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   zanzocam
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/zanzocam.rst

@@ -0,0 +1,71 @@
+zanzocam - Internal documentation
+=================================
+
+Documentation for the `constants.py` file and the `webcam` submodule.
+
+
+zanzocam.constants
+------------------
+
+.. automodule:: zanzocam.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+zanzocam.webcam.camera
+-----------------------------
+
+.. automodule:: zanzocam.webcam.camera
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+zanzocam.webcam.configuration
+-----------------------------
+
+.. automodule:: zanzocam.webcam.configuration
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+zanzocam.webcam.errors
+----------------------
+
+.. automodule:: zanzocam.webcam.errors
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+zanzocam.webcam.main
+--------------------
+
+.. automodule:: zanzocam.webcam.main
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+zanzocam.webcam.overlays
+------------------------
+
+.. automodule:: zanzocam.webcam.overlays
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+zanzocam.webcam.system
+----------------------
+
+.. automodule:: zanzocam.webcam.system
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+zanzocam.webcam.utils
+---------------------
+
+.. automodule:: zanzocam.webcam.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

setup.py

@@ -41,6 +41,10 @@
         'pytest-subprocess',
         'freezegun',  # Mock datetime objects
         'coveralls',  # To publish the coverage data on coveralls
+    ],
+    'docs': [
+        'sphinx',
+        'sphinx-rtd-theme',
     ]
 }
 

zanzocam/constants.py

@@ -2,104 +2,138 @@
 from pathlib import Path
 
 
+#: ZanzoCam version
 VERSION = "0.10.2"
 
 
-#
-# Paths & local URLs
-#
-
 # Executables constants
+# #####################
+
+
+#: Main user of the system, must be able to perform a passwordless sudo
 SYSTEM_USER = "zanzocam-bot"
+
+#: Location of the z-webcam executable
 ZANZOCAM_EXECUTABLE = "/home/zanzocam-bot/venv/bin/z-webcam"
 
+
 # Base paths
+# ##########
+
+#: Folder containing the source code
 BASE_PATH = Path(__file__).parent
+
+#: Folder containing the data used by the ZanzoCam for its operations
 DATA_PATH = BASE_PATH / "data" 
 
+
 # Log files
+# #########
+
+#: Logs of the local server (stay on disk and get rotated)
 SERVER_LOG = DATA_PATH / 'interface.log'
+
+#: Logs produced during the main procedure (will be sent to the server)
 CAMERA_LOG = DATA_PATH / 'camera.log'
-DIAGNOSTICS_LOG = DATA_PATH / 'diagnostics.log'
+
+#: Logs produced in case of issues with the server
 FAILURE_REPORT_PATH = DATA_PATH / 'failure_report.txt'
 
-# Configuration file
+#: Main configuration file
 CONFIGURATION_FILE = DATA_PATH / "configuration.json"
 
-# Setup related files
+#: Information about the Internet connection
 NETWORK_DATA = DATA_PATH / "network_data.json"
+
+#: (probably unused, TO CHECK)
 PICTURE_LOGS = DATA_PATH / "picture_logs.txt"
+
+#: (probably unused, TO CHECK)
 HOTSPOT_LOGS = DATA_PATH / "hotspot_logs.txt"
 
-# Flags (single value files)
+#: Whether the hotspot is allowed
 HOTSPOT_FLAG = DATA_PATH / "hotspot.flag"
 
-# Image paths (they have to be served out, so they go in the statics)
+#: URL to the preview picture in the web UI
 PREVIEW_PICTURE_URL =  "static/previews/zanzocam-preview.jpg"
+
+#: Path to the preview picture in the web UI
 PREVIEW_PICTURE = BASE_PATH / "web_ui" / PREVIEW_PICTURE_URL
 
-# Camera overlays
+#: Local camera overlays path
 IMAGE_OVERLAYS_PATH = DATA_PATH / "overlays"
+
+#: Remote camera overlays path
 REMOTE_IMAGES_PATH = "configuration/overlays/"
 
 
-#
 # Constants & defaults
-#
+# ####################
 
+#: Locale
 LOCALE = 'it_IT.utf8'
+
+#: Path to the default font (can be customized if you install another font)
 FONT_PATH = "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"
+
+#: Time to wait in between failed shots of the camera (to overcome colliding crontabs)
 WAIT_AFTER_CAMERA_FAIL = 30
 
-# Cronjob constants
+#: Temporary crontab path
 TEMP_CRONJOB = DATA_PATH / ".tmp-cronjob-file"
+
+#: Path to the crontab's backup
 BACKUP_CRONJOB = DATA_PATH / ".crontab.bak"
+
+#: Path to the system crontab
 CRONJOB_FILE = "/etc/cron.d/zanzocam"
 
-# System constants
+#: Timeout for HTTP requests
 REQUEST_TIMEOUT = 60
+
+#: URL to check to ensure Internet is reachable
 CHECK_UPLINK_URL = "http://www.google.com"
+
+#: Path to the autohotspot script
 AUTOHOTSPOT_BINARY_PATH = "/usr/bin/autohotspot"
 
-# Server constants
+#: Ecoding of the FTP server files
 FTP_CONFIG_FILE_ENCODING = 'utf-8'
 
 
+# Camera constants
+# ################
 
-#
-#  Camera constants
-#
-
-# Minimum luminance for the daytime. 
-# If the detected luminance goes below this value, the night mode kicks in.
+#: Minimum luminance for the daytime. 
+#:  If the detected luminance goes below this value, the night mode kicks in.
 MINIMUM_DAYLIGHT_LUMINANCE = 60
 
-# Minimum luminance to target for pictures in low light conditions.
+#: Minimum luminance to target for pictures in low light conditions.
 MINIMUM_NIGHT_LUMINANCE = 30
 
-# Starting ISO level for low light pictures
+#: Starting ISO level for low light pictures
 INITIAL_LOW_LIGHT_ISO = 400  
 
-# When to consider the image totally black, where the low light estimation doesn't work well
+#: When to consider the image totally black, where the low light estimation doesn't work well
 NO_LUMINANCE_THRESHOLD = 1  
 
-# What "random" shutter speed to use if the image is so black that the equation doesn't work
+#: What "random" shutter speed to use if the image is so black that the equation doesn't work
 NO_LUMINANCE_SHUTTER_SPEED = 2 * 10**6 
 
-# Min shutter speed for low light, the max that PiCamera would use with automatic settings
+#: Min shutter speed for low light, the max that PiCamera would use with automatic settings
 MIN_SHUTTER_SPEED = int(0.03 * 10**6)
 
-# Max shutter speed allowed by the camera hardware 
+#: Max shutter speed allowed by the camera hardware 
 MAX_SHUTTER_SPEED = int(9.5 * 10**6)
 
-# How much tolerance to give to the low light search algorithm
+#: How much tolerance to give to the low light search algorithm
 TARGET_LUMINOSITY_MARGIN = 3
 
-# Time to allow the firmware to compute the right exposure in normal 
-# light conditions (AWB requires more)
+#: Time to allow the firmware to compute the right exposure in normal 
+#:  light conditions (AWB requires more)
 CAMERA_WARM_UP_TIME = 5
 
-# White balancin modes from picamera
+#: White balancing modes from picamera
 PICAMERA_AWB_MODES = [
     'off',
     'auto',
@@ -113,7 +147,7 @@
     'horizon',
 ]
 
-# Fallback values for the camera configuration
+#: Fallback values for the camera configuration
 CAMERA_DEFAULTS = {
     "name": "no-name",
     "extension": "jpg",
@@ -135,6 +169,7 @@
     'let_awb_settle_in_dark': False,
 }
 
+#: Fallback values for the image overlays
 OVERLAY_DEFAULTS = {
     "font_size": 30,
     "padding": 50,