From 0150070b027e57c744fe33fb0094d5c9d3362a01 Mon Sep 17 00:00:00 2001 From: Konstantin Lampalzer Date: Sat, 16 Jan 2021 01:04:34 +0100 Subject: [PATCH] Add docs --- compLIB/Battery.py | 10 +++++--- compLIB/Buzzer.py | 18 ++++++++------ compLIB/IRSensor.py | 42 ++++++++++++++++++------------- compLIB/Motor.py | 8 +++--- compLIB/PCA9685.py | 7 +++--- compLIB/Servo.py | 10 +++++--- docs/.gitignore | 1 + docs/Makefile | 20 +++++++++++++++ docs/make.bat | 35 ++++++++++++++++++++++++++ docs/source/conf.py | 58 +++++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 25 +++++++++++++++++++ 11 files changed, 195 insertions(+), 39 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/compLIB/Battery.py b/compLIB/Battery.py index bb08b03..164309b 100644 --- a/compLIB/Battery.py +++ b/compLIB/Battery.py @@ -1,6 +1,5 @@ from compLIB.ADC import ADC - BATTERY_CHANNEL = 2 BATTERY_COUNT = 2 BATTERY_MULTIPLIER = 3 @@ -11,12 +10,15 @@ adc = ADC() class Battery(object): + """Used to interact with the battery + """ @staticmethod def percent() -> int: - """ - Get battery percentage between 0 and 100 - :return: + """Get battery percentage + + :return: Percentage between 0 and 100 + :rtype: int """ voltage = adc.read(BATTERY_CHANNEL) * BATTERY_MULTIPLIER return int((voltage - BATTERY_MIN_VOLTAGE) / BATTERY_MAX_VOLTAGE * 100) diff --git a/compLIB/Buzzer.py b/compLIB/Buzzer.py index 67869dd..58739ef 100644 --- a/compLIB/Buzzer.py +++ b/compLIB/Buzzer.py @@ -1,6 +1,7 @@ -import RPi.GPIO as GPIO import atexit +import RPi.GPIO as GPIO + GPIO.setwarnings(False) Buzzer_Pin = 17 GPIO.setmode(GPIO.BCM) @@ -8,17 +9,20 @@ GPIO.setup(Buzzer_Pin, GPIO.OUT) class Buzzer: + """Used to interact with the buzzer + """ @staticmethod def set(on: bool): - """ - Turn the buzzer on / off + """Turn the buzzer on / off + :param on: True if on, False if off - :return: None """ GPIO.output(Buzzer_Pin, on) -def exit(): - Buzzer.set(0) + @staticmethod + def exit(): + Buzzer.set(0) -atexit.register(exit) \ No newline at end of file + +atexit.register(Buzzer.exit) diff --git a/compLIB/IRSensor.py b/compLIB/IRSensor.py index 64f673d..c56076c 100644 --- a/compLIB/IRSensor.py +++ b/compLIB/IRSensor.py @@ -1,6 +1,7 @@ -from compLIB.ADC import ADC import RPi.GPIO as GPIO +from compLIB.ADC import ADC + TOP_LEFT_CHANNEL = 0 TOP_RIGHT_CHANNEL = 1 @@ -21,45 +22,52 @@ GPIO.setup(BOTTOM_RIGHT_PIN, GPIO.IN) class IRSensor(object): + """Access the different IR Sensors at top / bottom of the robot + """ @staticmethod def top_left_percent() -> int: - """ - Get left infrared sensor percentage between 0 and 100 - :return: + """Get top left infrared sensor percentage + + :return: Percentage between 0 and 100 + :rtype: int """ voltage = adc.read(TOP_LEFT_CHANNEL) return int((voltage - TOP_IR_MIN_VOLTAGE) / TOP_IR_MAX_VOLTAGE * 100) @staticmethod def top_right_percent() -> int: - """ - Get right infrared sensor percentage between 0 and 100 - :return: + """Get top right infrared sensor percentage + + :return: Percentage between 0 and 100 + :rtype: int """ voltage = adc.read(TOP_RIGHT_CHANNEL) return int((voltage - TOP_IR_MIN_VOLTAGE) / TOP_IR_MAX_VOLTAGE * 100) @staticmethod def bottom_left() -> bool: - """ - Get status of bottom infrared sensor - :return: bool + """Get bottom left infrared sensor status + + :return: True, if sensor detects IR signals + :rtype: bool """ return GPIO.input(BOTTOM_LEFT_PIN) @staticmethod def bottom_middle() -> bool: - """ - Get status of bottom infrared sensor - :return: bool + """Get bottom middle infrared sensor status + + :return: True, if sensor detects IR signals + :rtype: bool """ return GPIO.input(BOTTOM_MIDDLE_PIN) @staticmethod def bottom_right() -> bool: + """Get bottom right infrared sensor status + + :return: True, if sensor detects IR signals + :rtype: bool """ - Get status of bottom infrared sensor - :return: bool - """ - return GPIO.input(BOTTOM_RIGHT_PIN) \ No newline at end of file + return GPIO.input(BOTTOM_RIGHT_PIN) diff --git a/compLIB/Motor.py b/compLIB/Motor.py index ea68870..5d29f7b 100644 --- a/compLIB/Motor.py +++ b/compLIB/Motor.py @@ -11,14 +11,15 @@ MOTOR_PERCENTAGE_MULT = MAX_MOTOR_SPEED / 100.0 class Motor(object): + """Class used to control the motors + """ @staticmethod def power(port: int, percent: int): - """ - Set specified motor to percentage power + """Set specified motor to percentage power + :param port: Port, which the motor is connected to. 0-3, 0 -> top left, 3 -> top right :param percent: Percentage of max speed. between -100 and 100 - :return: None """ forward = True if percent < 0: @@ -42,7 +43,6 @@ class Motor(object): def all_off(): """ Turns of all motors - :return: """ for i in range(0, MOTOR_COUNT): Motor.power(i, 0) diff --git a/compLIB/PCA9685.py b/compLIB/PCA9685.py index 86b3d40..b2b3513 100644 --- a/compLIB/PCA9685.py +++ b/compLIB/PCA9685.py @@ -1,7 +1,8 @@ #!/usr/bin/python -import time import math +import time + import smbus @@ -48,7 +49,7 @@ class PCA9685: prescaleval -= 1.0 prescale = math.floor(prescaleval + 0.5) - oldmode = self.read(self.__MODE1); + oldmode = self.read(self.__MODE1) newmode = (oldmode & 0x7F) | 0x10 # sleep self.write(self.__MODE1, newmode) # go to sleep self.write(self.__PRESCALE, int(math.floor(prescale))) @@ -73,4 +74,4 @@ class PCA9685: if __name__ == '__main__': - pass \ No newline at end of file + pass diff --git a/compLIB/Servo.py b/compLIB/Servo.py index 0a6ba68..c7674bb 100644 --- a/compLIB/Servo.py +++ b/compLIB/Servo.py @@ -5,15 +5,15 @@ pwm.setPWMFreq(50) class Servo: + """Control the servo ports on the robot + """ @staticmethod def set_position(channel: int, angle: int): - """ - Set position of servo connected to port + """Set position of servo connected to port + :param channel: channel between 0 and 7 :param angle: Angle of servo - :return: None - """ angle = abs(angle) @@ -24,5 +24,7 @@ class Servo: @staticmethod def setup_position(): + """Set position of servos to the position used during the setup process + """ pwm.setServoPulse(8, 1500) pwm.setServoPulse(9, 1500) diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..c795b05 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +build \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /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/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..66a39ca --- /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('../..')) +sys.setrecursionlimit(1500) + +# -- Project information ----------------------------------------------------- + +project = 'CompLib' +copyright = '2021, robo4you' +author = 'robo4you' + +# The full version, including alpha/beta/rc tags +release = '0.0.1' + +# -- 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_rtd_theme' +] + +autodoc_mock_imports = ["smbus", "compLIB.PCA9685", "RPi"] + +# 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 0000000..c207a90 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,25 @@ +Welcome to CompLib's documentation! +=================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + + +Table of Contents +^^^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 5 + :glob: + + self + lib/*