From 5dba111e657237be430fd3d03f42d2e093917015 Mon Sep 17 00:00:00 2001 From: ZanSara Date: Wed, 9 Jun 2021 23:18:21 +0200 Subject: [PATCH] Add stup of the Sphinx internal docs --- .gitignore | 4 +- docs/.nojekyll | 0 docs/Makefile | 20 ++++++++ docs/source/conf.py | 58 +++++++++++++++++++++++ docs/source/index.rst | 16 +++++++ docs/source/zanzocam.rst | 71 ++++++++++++++++++++++++++++ setup.py | 4 ++ zanzocam/constants.py | 99 +++++++++++++++++++++++++++------------- 8 files changed, 239 insertions(+), 33 deletions(-) create mode 100644 docs/.nojekyll create mode 100644 docs/Makefile create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/zanzocam.rst diff --git a/.gitignore b/.gitignore index 0122d8b4..0e092e6f 100644 --- a/.gitignore +++ b/.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 diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/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) diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..67d196d9 --- /dev/null +++ b/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'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..ef7ae0c5 --- /dev/null +++ b/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` diff --git a/docs/source/zanzocam.rst b/docs/source/zanzocam.rst new file mode 100644 index 00000000..bb3626ca --- /dev/null +++ b/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: + diff --git a/setup.py b/setup.py index 744f51c1..15983825 100644 --- a/setup.py +++ b/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', ] } diff --git a/zanzocam/constants.py b/zanzocam/constants.py index 8171e9a3..4edd7d2e 100644 --- a/zanzocam/constants.py +++ b/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,