From c31f9f28bc729d432b7d06da811a2fe5cebfbc88 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:00:58 -0700 Subject: [PATCH 01/25] added github workflow --- .github/workflows/build-docs.yml | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 .github/workflows/build-docs.yml diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 0000000..6af230d --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,30 @@ +name: Build Documentation + +on: + push: + branches: [ master ] + pull_request: + branches: [ master ] + +jobs: + build-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Set up Python 3.8 + uses: actions/setup-python@v2 + with: + python-version: 3.8 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install sphinx + - name: Build documentation + run: | + cd docs + make html + - name: Deploy documentation + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html From bcbd23012b095c01f49d9eee6750300b996be0c9 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:07:24 -0700 Subject: [PATCH 02/25] Update build-docs.yml --- .github/workflows/build-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 6af230d..a493807 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -24,7 +24,7 @@ jobs: cd docs make html - name: Deploy documentation - uses: peaceiris/actions-gh-pages@v3 + uses: ansarid/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs/_build/html From fe48fdb52b61002f0312ca80d1808a7b755e61b7 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:13:24 -0700 Subject: [PATCH 03/25] Update build-docs.yml --- .github/workflows/build-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index a493807..6af230d 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -24,7 +24,7 @@ jobs: cd docs make html - name: Deploy documentation - uses: ansarid/actions-gh-pages@v3 + uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs/_build/html From c2cdccee6ed25f3c83db00031cdaa9409852b9ca Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:16:26 -0700 Subject: [PATCH 04/25] Update build-docs.yml --- .github/workflows/build-docs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 6af230d..86ae7ec 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -11,10 +11,13 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 + with: + node-version: 16 - name: Set up Python 3.8 uses: actions/setup-python@v2 with: python-version: 3.8 + node-version: 16 - name: Install dependencies run: | python -m pip install --upgrade pip From 59462d6bd784dfca6fb329a93e9ecff8fb60fd8c Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:19:47 -0700 Subject: [PATCH 05/25] added docs --- docs/Makefile | 20 ++++++++++++++++++++ docs/conf.py | 27 +++++++++++++++++++++++++++ docs/index.rst | 20 ++++++++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++++++++++++ 4 files changed, 102 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /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 = . +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/conf.py b/docs/conf.py new file mode 100644 index 0000000..6c3740b --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,27 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'DDController' +copyright = '2022, Daniyal Ansari' +author = 'Daniyal Ansari' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..35412f3 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. DDController documentation master file, created by + sphinx-quickstart on Fri Dec 30 10:19:32 2022. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to DDController's documentation! +======================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /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=. +set BUILDDIR=_build + +%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.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd From 8c7990763be1b11f6f2de058c2002e4f61d4d1a5 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:26:40 -0700 Subject: [PATCH 06/25] docs --- docs/conf.py | 4 ++-- docs/index.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 6c3740b..60729ed 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,7 +13,7 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [] +extensions = ['sphinx.ext.autodoc',] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] @@ -23,5 +23,5 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' html_static_path = ['_static'] diff --git a/docs/index.rst b/docs/index.rst index 35412f3..b882bee 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,7 +10,7 @@ Welcome to DDController's documentation! :maxdepth: 2 :caption: Contents: - + modules Indices and tables ================== From 4043f7042d947fdfea5ed004a567db15fb817bc2 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:29:27 -0700 Subject: [PATCH 07/25] fixed docs? --- .github/workflows/build-docs.yml | 2 +- docs/conf.py | 9 +++++++-- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 86ae7ec..00b5047 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -21,7 +21,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install sphinx + pip install sphinx sphinx.ext.autodoc sphinx_rtd_theme - name: Build documentation run: | cd docs diff --git a/docs/conf.py b/docs/conf.py index 60729ed..d5e53bb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,5 +23,10 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'sphinx_rtd_theme' -html_static_path = ['_static'] +import sphinx_rtd_theme + +html_theme = "sphinx_rtd_theme" +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +#html_theme = 'sphinx_rtd_theme' +#html_static_path = ['_static'] From ac2867ce2b5d8ba19ebea6bffea174eef2ade490 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:33:04 -0700 Subject: [PATCH 08/25] docs --- docs/conf.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d5e53bb..e0e81ca 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,7 +13,9 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ['sphinx.ext.autodoc',] +extensions = [ + "sphinx.ext.autodoc", +] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] @@ -25,8 +27,8 @@ import sphinx_rtd_theme -html_theme = "sphinx_rtd_theme" -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +#html_theme = "sphinx_rtd_theme" +#html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] -#html_theme = 'sphinx_rtd_theme' -#html_static_path = ['_static'] +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] From 14fb5245632b3671ad392fbcd54a285b4f63a956 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:38:36 -0700 Subject: [PATCH 09/25] undid docs theme --- docs/conf.py | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e0e81ca..03f9753 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,8 +27,5 @@ import sphinx_rtd_theme -#html_theme = "sphinx_rtd_theme" -#html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - -html_theme = 'sphinx_rtd_theme' +html_theme = 'alabaster' html_static_path = ['_static'] From 215b3809269d3fd3bc08f756a9d54ac38b42e651 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:39:22 -0700 Subject: [PATCH 10/25] removed autodoc --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 03f9753..51456e7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,7 +14,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ - "sphinx.ext.autodoc", +# "sphinx.ext.autodoc", ] templates_path = ['_templates'] From 7cfbd2df818e499befa3dd126b03ade1dd9a5fc4 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:40:33 -0700 Subject: [PATCH 11/25] removed rtd import --- docs/conf.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 51456e7..e39ceac 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,7 +25,5 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -import sphinx_rtd_theme - html_theme = 'alabaster' html_static_path = ['_static'] From 89d171b2b78340b406c7b88000adac9ae6c1f6e6 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:43:11 -0700 Subject: [PATCH 12/25] autodocs --- .github/workflows/build-docs.yml | 2 +- docs/conf.py | 4 +--- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 00b5047..fa2b43b 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -21,7 +21,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install sphinx sphinx.ext.autodoc sphinx_rtd_theme + pip install sphinx sphinx-autodocgen sphinx_rtd_theme - name: Build documentation run: | cd docs diff --git a/docs/conf.py b/docs/conf.py index e39ceac..6c3740b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,9 +13,7 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [ -# "sphinx.ext.autodoc", -] +extensions = [] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] From bfb71b5cf61e8a9d8e807d930acb810ecd40de74 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:50:07 -0700 Subject: [PATCH 13/25] docs testing --- .github/workflows/build-docs.yml | 26 +++++++++----------------- 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index fa2b43b..d60c8e3 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -1,33 +1,25 @@ -name: Build Documentation +name: Documentation -on: - push: - branches: [ master ] - pull_request: - branches: [ master ] +on: [push] jobs: - build-docs: + build: runs-on: ubuntu-latest + steps: - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 with: - node-version: 16 - - name: Set up Python 3.8 - uses: actions/setup-python@v2 - with: - python-version: 3.8 - node-version: 16 + python-version: '3.x' - name: Install dependencies run: | - python -m pip install --upgrade pip - pip install sphinx sphinx-autodocgen sphinx_rtd_theme + python -m pip install -r requirements.txt + python -m pip install sphinx sphinx-rtd-theme - name: Build documentation run: | - cd docs make html - name: Deploy documentation uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./docs/_build/html + publish_dir: build/html From 2afe32aee8f89c5e7264f56b6c2fdffc84bfd3a5 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:52:03 -0700 Subject: [PATCH 14/25] Update build-docs.yml --- .github/workflows/build-docs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index d60c8e3..835c53d 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -13,7 +13,6 @@ jobs: python-version: '3.x' - name: Install dependencies run: | - python -m pip install -r requirements.txt python -m pip install sphinx sphinx-rtd-theme - name: Build documentation run: | From 6f55e05abad9675f2c98cb4eceef6afe49ae13d7 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Fri, 30 Dec 2022 10:53:59 -0700 Subject: [PATCH 15/25] Revert "added docstring" This reverts commit a20726be78a725fd53960f8f44d7b15c534e0cb8. --- ddcontroller/ddcontroller.py | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/ddcontroller/ddcontroller.py b/ddcontroller/ddcontroller.py index 25a8840..817a780 100644 --- a/ddcontroller/ddcontroller.py +++ b/ddcontroller/ddcontroller.py @@ -141,20 +141,12 @@ def __init__(self, config_path='/opt/ddcontroller/config/default.yaml', debug=Fa self.position_controller_thread.start() # start position contoller thread # Ideally we don't start this until it's needed def sleep(self, start_time): - """Sleep for a specified amount of time. - - This method calculates the amount of time that has passed since the start time - and subtracts that from the wait time specified in the `self._wait` attribute. - If the calculated sleep time is negative, it is set to 0 instead. The method - then calls the built-in `time.sleep()` method to pause the program for the - calculated amount of time. + """_summary_ Args: - start_time (int): The starting timestamp in nanoseconds. - - Returns: - float: The amount of time slept in seconds. + start_time (_type_): _description_ """ + # measure time since start and subtract from sleep time sleep_time = sorted( [self._wait - ((time.monotonic_ns() - start_time) / 1e9), 0] )[1] @@ -169,8 +161,8 @@ def _odometry_loop(self): start_time = time.monotonic_ns() # record loop start time - self.left_wheel.update() # update left wheel readings - self.right_wheel.update() # update right wheel readings + self.left_wheel.update() # update left wheel readings + self.right_wheel.update() # update right wheel readings self.linear_velocity, self.angular_velocity = self.get_motion() # get robot linear and angular velocities From 59caae90a05d744b65a2a7d6b8887e01281bfd1b Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Sat, 31 Dec 2022 09:20:25 -0700 Subject: [PATCH 16/25] added workflow again --- .github/workflows/build-docs.yml | 19 ++++++++++------ docs/Makefile | 4 ++-- docs/ddcontroller.rst | 37 ++++++++++++++++++++++++++++++++ docs/make.bat | 4 ++-- docs/modules.rst | 7 ++++++ docs/{ => source}/conf.py | 18 ++++++++++++++-- docs/{ => source}/index.rst | 2 +- 7 files changed, 77 insertions(+), 14 deletions(-) create mode 100644 docs/ddcontroller.rst create mode 100644 docs/modules.rst rename docs/{ => source}/conf.py (66%) rename docs/{ => source}/index.rst (89%) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 835c53d..1b49502 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -1,24 +1,29 @@ -name: Documentation +name: Build and Deploy Documentation -on: [push] +on: + push: + branches: + - documentation jobs: build: runs-on: ubuntu-latest - steps: - uses: actions/checkout@v2 - - uses: actions/setup-python@v2 + - name: Set up Python + uses: actions/setup-python@v2 with: - python-version: '3.x' + python-version: 3.8 - name: Install dependencies run: | - python -m pip install sphinx sphinx-rtd-theme + python -m pip install --upgrade pip + pip install sphinx - name: Build documentation run: | + cd path/to/your/library/docs make html - name: Deploy documentation uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: build/html + publish_dir: path/to/your/library/docs/build/html diff --git a/docs/Makefile b/docs/Makefile index d4bb2cb..d0c3cbf 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,8 +5,8 @@ # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build +SOURCEDIR = source +BUILDDIR = build # Put it first so that "make" without argument is like "make help". help: diff --git a/docs/ddcontroller.rst b/docs/ddcontroller.rst new file mode 100644 index 0000000..11ad258 --- /dev/null +++ b/docs/ddcontroller.rst @@ -0,0 +1,37 @@ +ddcontroller package +==================== + +Submodules +---------- + +ddcontroller.ddcontroller module +-------------------------------- + +.. automodule:: ddcontroller.ddcontroller + :members: + :undoc-members: + :show-inheritance: + +ddcontroller.motor module +------------------------- + +.. automodule:: ddcontroller.motor + :members: + :undoc-members: + :show-inheritance: + +ddcontroller.wheels module +-------------------------- + +.. automodule:: ddcontroller.wheels + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: ddcontroller + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/make.bat b/docs/make.bat index 32bb245..747ffb7 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -7,8 +7,8 @@ REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) -set SOURCEDIR=. -set BUILDDIR=_build +set SOURCEDIR=source +set BUILDDIR=build %SPHINXBUILD% >NUL 2>NUL if errorlevel 9009 ( diff --git a/docs/modules.rst b/docs/modules.rst new file mode 100644 index 0000000..79b0831 --- /dev/null +++ b/docs/modules.rst @@ -0,0 +1,7 @@ +ddcontroller +============ + +.. toctree:: + :maxdepth: 4 + + ddcontroller diff --git a/docs/conf.py b/docs/source/conf.py similarity index 66% rename from docs/conf.py rename to docs/source/conf.py index 6c3740b..cb49d2e 100644 --- a/docs/conf.py +++ b/docs/source/conf.py @@ -13,10 +13,12 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [] +extensions = [ + 'sphinx.ext.autodoc', +] templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = [] @@ -25,3 +27,15 @@ html_theme = 'alabaster' html_static_path = ['_static'] + + + +# -- 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('..')) diff --git a/docs/index.rst b/docs/source/index.rst similarity index 89% rename from docs/index.rst rename to docs/source/index.rst index b882bee..50556b0 100644 --- a/docs/index.rst +++ b/docs/source/index.rst @@ -1,5 +1,5 @@ .. DDController documentation master file, created by - sphinx-quickstart on Fri Dec 30 10:19:32 2022. + sphinx-quickstart on Sat Dec 31 09:10:54 2022. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. From 16404d1e1012ba92ae1bdac399691b3a617e8538 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Sat, 31 Dec 2022 09:22:23 -0700 Subject: [PATCH 17/25] work --- .github/workflows/build-docs.yml | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 6af230d..6385a40 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -1,17 +1,16 @@ -name: Build Documentation +name: Build and Deploy Documentation on: push: - branches: [ master ] - pull_request: - branches: [ master ] + branches: + - documented jobs: - build-docs: + build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - - name: Set up Python 3.8 + - name: Set up Python uses: actions/setup-python@v2 with: python-version: 3.8 @@ -21,10 +20,10 @@ jobs: pip install sphinx - name: Build documentation run: | - cd docs + cd path/to/your/library/docs make html - name: Deploy documentation uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./docs/_build/html + publish_dir: path/to/your/library/docs/build/html From b9447360466ff0010a2f7c63eeb8616daea4b0d8 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Sat, 31 Dec 2022 09:29:24 -0700 Subject: [PATCH 18/25] publish_path --- .github/workflows/build-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 6385a40..064026c 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -26,4 +26,4 @@ jobs: uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: path/to/your/library/docs/build/html + publish_dir: ./docs/build/html From efd1eb6d4d97d40263e88b0093ef3eb4a0398aa3 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Sat, 31 Dec 2022 09:30:33 -0700 Subject: [PATCH 19/25] docs --- .github/workflows/build-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 064026c..5909a77 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -20,7 +20,7 @@ jobs: pip install sphinx - name: Build documentation run: | - cd path/to/your/library/docs + cd ./docs make html - name: Deploy documentation uses: peaceiris/actions-gh-pages@v3 From ad3b6292103d371c38ac84a66354a2c701f15a10 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Sat, 31 Dec 2022 10:35:43 -0700 Subject: [PATCH 20/25] working docs --- .github/workflows/build-docs.yml | 3 ++- docs/Makefile | 4 ++-- docs/{source => }/conf.py | 26 ++++++++++++-------------- docs/{source => }/index.rst | 2 +- docs/make.bat | 4 ++-- docs/setup.rst | 7 +++++++ 6 files changed, 26 insertions(+), 20 deletions(-) rename docs/{source => }/conf.py (69%) rename docs/{source => }/index.rst (89%) create mode 100644 docs/setup.rst diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 5909a77..a974e21 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -18,6 +18,7 @@ jobs: run: | python -m pip install --upgrade pip pip install sphinx + pip install mock - name: Build documentation run: | cd ./docs @@ -26,4 +27,4 @@ jobs: uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./docs/build/html + publish_dir: ./docs/build/html \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf..d4bb2cb 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,8 +5,8 @@ # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build +SOURCEDIR = . +BUILDDIR = _build # Put it first so that "make" without argument is like "make help". help: diff --git a/docs/source/conf.py b/docs/conf.py similarity index 69% rename from docs/source/conf.py rename to docs/conf.py index cb49d2e..cb9d6e1 100644 --- a/docs/source/conf.py +++ b/docs/conf.py @@ -6,6 +6,10 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information +import os +import sys +sys.path.insert(0, os.path.abspath("..")) + project = 'DDController' copyright = '2022, Daniyal Ansari' author = 'Daniyal Ansari' @@ -15,27 +19,21 @@ extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.viewcode', ] +autodoc_mock_imports = ['mock', 'RPi.GPIO', 'as5048b'] + templates_path = ['_templates'] -exclude_patterns = [] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' html_static_path = ['_static'] - - - -# -- 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('..')) diff --git a/docs/source/index.rst b/docs/index.rst similarity index 89% rename from docs/source/index.rst rename to docs/index.rst index 50556b0..dc2ff91 100644 --- a/docs/source/index.rst +++ b/docs/index.rst @@ -1,5 +1,5 @@ .. DDController documentation master file, created by - sphinx-quickstart on Sat Dec 31 09:10:54 2022. + sphinx-quickstart on Sat Dec 31 10:09:28 2022. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. diff --git a/docs/make.bat b/docs/make.bat index 747ffb7..32bb245 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -7,8 +7,8 @@ REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) -set SOURCEDIR=source -set BUILDDIR=build +set SOURCEDIR=. +set BUILDDIR=_build %SPHINXBUILD% >NUL 2>NUL if errorlevel 9009 ( diff --git a/docs/setup.rst b/docs/setup.rst new file mode 100644 index 0000000..552eb49 --- /dev/null +++ b/docs/setup.rst @@ -0,0 +1,7 @@ +setup module +============ + +.. automodule:: setup + :members: + :undoc-members: + :show-inheritance: From 01c441274ba82b89583ebad76a49e4f8c4c183b6 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Sat, 31 Dec 2022 10:39:17 -0700 Subject: [PATCH 21/25] attempt 2 --- .github/workflows/build-docs.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index a974e21..13e9b70 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -17,8 +17,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install sphinx - pip install mock + pip install sphinx sphinx_rtd_theme mock - name: Build documentation run: | cd ./docs From 9a11d66536da9b4a9caf44b6714b2344c48c3b34 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Sat, 31 Dec 2022 10:48:12 -0700 Subject: [PATCH 22/25] updated makefiule --- docs/Makefile | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index d4bb2cb..773fbc9 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,8 +3,9 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = DDController SOURCEDIR = . BUILDDIR = _build @@ -17,4 +18,11 @@ help: # 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) + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +# Build the documentation +html: + $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +clean: + rm -rf "$(BUILDDIR)" \ No newline at end of file From f43b8cabf21d76369320fe6a0d7937aa49bf4605 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Sun, 1 Jan 2023 13:43:47 -0700 Subject: [PATCH 23/25] fixed docstrings --- ddcontroller/ddcontroller.py | 14 +++---- ddcontroller/motor.py | 28 +++++++------ ddcontroller/wheels.py | 81 ++++++++++++++++++------------------ 3 files changed, 63 insertions(+), 60 deletions(-) diff --git a/ddcontroller/ddcontroller.py b/ddcontroller/ddcontroller.py index 817a780..4357df2 100644 --- a/ddcontroller/ddcontroller.py +++ b/ddcontroller/ddcontroller.py @@ -31,16 +31,16 @@ class DDRobot: - """Initialize a DDRobot object. + def __init__(self, config_path='/opt/ddcontroller/config/default.yaml', debug=False): - This method initializes a DDRobot object by setting up the wheels and loading the configuration from a YAML file. The robot has various attributes such as its heading, linear velocity, and global position, as well as target motion, heading, and position. The robot also has various constants such as its wheel base, maximum linear and angular velocities, and tolerance for reaching the target position. + """Initialize a DDRobot object. - Args: - config_path (str, optional): The path to the YAML configuration file. Defaults to '/opt/ddcontroller/config/default.yaml'. - debug (bool, optional): Whether to print debugging messages. Defaults to False. - """ + This method initializes a DDRobot object by setting up the wheels and loading the configuration from a YAML file. The robot has various attributes such as its heading, linear velocity, and global position, as well as target motion, heading, and position. The robot also has various constants such as its wheel base, maximum linear and angular velocities, and tolerance for reaching the target position. - def __init__(self, config_path='/opt/ddcontroller/config/default.yaml', debug=False): + Args: + config_path (str, optional): The path to the YAML configuration file. Defaults to '/opt/ddcontroller/config/default.yaml'. + debug (bool, optional): Whether to print debugging messages. Defaults to False. + """ self.config = yaml.load(open(config_path, "r", encoding="utf-8").read()) self.debug = debug diff --git a/ddcontroller/motor.py b/ddcontroller/motor.py index 0b14bff..477dca6 100644 --- a/ddcontroller/motor.py +++ b/ddcontroller/motor.py @@ -22,21 +22,23 @@ GPIO.setwarnings(False) class Motor: - """Class for controlling a motor using the Raspberry Pi's GPIO pins. - - Args: - pins (list): A list of the GPIO pins that will be used to control the motor. - pwm_frequency (int): The frequency of the pulse width modulation (PWM) signal - that will be used to control the motor. - initial_duty (int, optional): The initial duty cycle of the PWM signal. Defaults to 0. - decay_mode (str, optional): The decay mode of the motor. Can be either "FAST" or - "SLOW". Defaults to "FAST". - invert (bool, optional): A boolean value indicating whether the motor's direction - should be reversed. Defaults to False. - rpm (int, optional): The speed of the motor in rotations per minute. Defaults to 200. - """ def __init__(self, pins, pwm_frequency, initial_duty=0, decay_mode='FAST', invert=False, rpm=200): + + """Class for controlling a motor using the Raspberry Pi's GPIO pins. + + Args: + pins (list): A list of the GPIO pins that will be used to control the motor. + pwm_frequency (int): The frequency of the pulse width modulation (PWM) signal + that will be used to control the motor. + initial_duty (int, optional): The initial duty cycle of the PWM signal. Defaults to 0. + decay_mode (str, optional): The decay mode of the motor. Can be either "FAST" or + "SLOW". Defaults to "FAST". + invert (bool, optional): A boolean value indicating whether the motor's direction + should be reversed. Defaults to False. + rpm (int, optional): The speed of the motor in rotations per minute. Defaults to 200. + """ + self.pins = pins self._pins = [] diff --git a/ddcontroller/wheels.py b/ddcontroller/wheels.py index 4a5e2bd..acce053 100644 --- a/ddcontroller/wheels.py +++ b/ddcontroller/wheels.py @@ -28,46 +28,6 @@ class Wheel: - """A class for representing and controlling a single wheel. - - This class represents a single wheel, including its motor and encoder, and provides methods for controlling the speed of the motor and calculating the rotation and linear velocity of the wheel. - - Attributes: - closed_loop (bool): A flag indicating whether closed loop control should be used to control the motor. - motor (Motor): An instance of the Motor class representing the motor driving the wheel. - encoder (AS5048B): An instance of the AS5048B class representing the encoder attached to the wheel. - pid (PID): An instance of the PID class representing the PID controller used for closed loop control. - radius (float): The radius of the wheel, in meters. - pulley_ratio (float): The ratio of the number of teeth on the motor pulley to the number of teeth on the wheel pulley. - rpm (float): The rotational speed of the motor, in revolutions per minute. - max_angular_velocity (float): The maximum angular velocity of the wheel, in radians per second, based on the maximum RPM of the motor. - target_angular_velocity (float): The target angular velocity of the system, in radians per second, used to control the motor. - position (int): The raw encoder position of the wheel, in ticks. - timestamp (int): The timestamp of the last measurement of the encoder position, in nanoseconds. - target_velocity (float): The target linear velocity of the wheel, in meters per second. - angular_velocity (float): The current angular velocity of the wheel, in radians per second. - linear_velocity (float): The current linear velocity of the wheel, in meters per second. - rollover_limit (int): The limit at which the encoder position will rollover, in ticks. - _positions (deque): A deque object containing the last two encoder positions of the wheel, in ticks. - _timestamps (deque): A deque object containing the timestamps of the last two encoder position measurements, in nanoseconds. - - Args: - motor_pins (tuple): A tuple containing the pins of the motor driver connected to the motor. - pwm_frequency (int): The frequency of the pulse width modulation used to control the motor, in hertz. - i2c_bus (int): The number of the I2C bus on which the encoder is connected. - encoder_address (int): The I2C address of the encoder. - wheel_radius (float): The radius of the wheel, in meters. - motor_pulley_teeth (int): The number of teeth on the pulley attached to the motor shaft. - wheel_pulley_teeth (int): The number of teeth on the pulley attached to the wheel hub. - motor_decay_mode (str, optional): The decay mode of the motor. Can be 'FAST' or 'SLOW'. Defaults to 'FAST'. - invert_motor (bool, optional): A flag indicating whether the motor should be inverted. Defaults to False. - invert_encoder (bool, optional): A flag indicating whether the encoder readings should be inverted. Defaults to False. - closed_loop (bool, optional): A flag indicating whether closed loop control should be used to control the motor. Defaults to False. - Kp (int, optional): The proportional gain of the PID controller. Defaults to 0. - Ki (int, optional): The integral gain of the PID controller. Defaults to 0. - Kd (int, optional): The derivative gain of the PID controller. Defaults to 0. - """ - def __init__( self, motor_pins, @@ -86,6 +46,47 @@ def __init__( Kd=0, ): + """A class for representing and controlling a single wheel. + + This class represents a single wheel, including its motor and encoder, and provides methods for controlling the speed of the motor and calculating the rotation and linear velocity of the wheel. + + Attributes: + closed_loop (bool): A flag indicating whether closed loop control should be used to control the motor. + motor (Motor): An instance of the Motor class representing the motor driving the wheel. + encoder (AS5048B): An instance of the AS5048B class representing the encoder attached to the wheel. + pid (PID): An instance of the PID class representing the PID controller used for closed loop control. + radius (float): The radius of the wheel, in meters. + pulley_ratio (float): The ratio of the number of teeth on the motor pulley to the number of teeth on the wheel pulley. + rpm (float): The rotational speed of the motor, in revolutions per minute. + max_angular_velocity (float): The maximum angular velocity of the wheel, in radians per second, based on the maximum RPM of the motor. + target_angular_velocity (float): The target angular velocity of the system, in radians per second, used to control the motor. + position (int): The raw encoder position of the wheel, in ticks. + timestamp (int): The timestamp of the last measurement of the encoder position, in nanoseconds. + target_velocity (float): The target linear velocity of the wheel, in meters per second. + angular_velocity (float): The current angular velocity of the wheel, in radians per second. + linear_velocity (float): The current linear velocity of the wheel, in meters per second. + rollover_limit (int): The limit at which the encoder position will rollover, in ticks. + _positions (deque): A deque object containing the last two encoder positions of the wheel, in ticks. + _timestamps (deque): A deque object containing the timestamps of the last two encoder position measurements, in nanoseconds. + + Args: + motor_pins (tuple): A tuple containing the pins of the motor driver connected to the motor. + pwm_frequency (int): The frequency of the pulse width modulation used to control the motor, in hertz. + i2c_bus (int): The number of the I2C bus on which the encoder is connected. + encoder_address (int): The I2C address of the encoder. + wheel_radius (float): The radius of the wheel, in meters. + motor_pulley_teeth (int): The number of teeth on the pulley attached to the motor shaft. + wheel_pulley_teeth (int): The number of teeth on the pulley attached to the wheel hub. + motor_decay_mode (str, optional): The decay mode of the motor. Can be 'FAST' or 'SLOW'. Defaults to 'FAST'. + invert_motor (bool, optional): A flag indicating whether the motor should be inverted. Defaults to False. + invert_encoder (bool, optional): A flag indicating whether the encoder readings should be inverted. Defaults to False. + closed_loop (bool, optional): A flag indicating whether closed loop control should be used to control the motor. Defaults to False. + Kp (int, optional): The proportional gain of the PID controller. Defaults to 0. + Ki (int, optional): The integral gain of the PID controller. Defaults to 0. + Kd (int, optional): The derivative gain of the PID controller. Defaults to 0. + """ + + self.closed_loop = closed_loop self.motor = motor.Motor( From e739998716e60de22dd87c401ea4a9eb4118ec58 Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Mon, 2 Jan 2023 22:37:23 -0700 Subject: [PATCH 24/25] changed comments --- ddcontroller/__init__.py | 28 ++++++++++++++-------------- ddcontroller/ddcontroller.py | 34 +++++++++++++++++----------------- ddcontroller/motor.py | 34 +++++++++++++++++----------------- ddcontroller/wheels.py | 34 +++++++++++++++++----------------- 4 files changed, 65 insertions(+), 65 deletions(-) diff --git a/ddcontroller/__init__.py b/ddcontroller/__init__.py index 376f4c9..b46edbc 100644 --- a/ddcontroller/__init__.py +++ b/ddcontroller/__init__.py @@ -1,21 +1,21 @@ #!/usr/bin/env python3 -''' -This file is part of the ddcontroller library (https://github.com/ansarid/ddcontroller). -Copyright (C) 2022 Daniyal Ansari -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. +# This file is part of the ddcontroller library (https://github.com/ansarid/ddcontroller). +# Copyright (C) 2022 Daniyal Ansari -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . -You should have received a copy of the GNU General Public License -along with this program. If not, see . -''' from .ddcontroller import * diff --git a/ddcontroller/ddcontroller.py b/ddcontroller/ddcontroller.py index 4357df2..637e28c 100644 --- a/ddcontroller/ddcontroller.py +++ b/ddcontroller/ddcontroller.py @@ -1,22 +1,22 @@ #!/usr/bin/env python3 -''' -This file is part of the ddcontroller library (https://github.com/ansarid/ddcontroller). -Copyright (C) 2022 Daniyal Ansari - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see . -''' + +# This file is part of the ddcontroller library (https://github.com/ansarid/ddcontroller). +# Copyright (C) 2022 Daniyal Ansari + +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + import time import threading diff --git a/ddcontroller/motor.py b/ddcontroller/motor.py index 477dca6..668ce6d 100644 --- a/ddcontroller/motor.py +++ b/ddcontroller/motor.py @@ -1,22 +1,22 @@ #!/usr/bin/env python3 -''' -This file is part of the ddcontroller library (https://github.com/ansarid/ddcontroller). -Copyright (C) 2022 Daniyal Ansari - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see . -''' + +# This file is part of the ddcontroller library (https://github.com/ansarid/ddcontroller). +# Copyright (C) 2022 Daniyal Ansari + +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + import RPi.GPIO as GPIO GPIO.setwarnings(False) diff --git a/ddcontroller/wheels.py b/ddcontroller/wheels.py index acce053..1ab8471 100644 --- a/ddcontroller/wheels.py +++ b/ddcontroller/wheels.py @@ -1,22 +1,22 @@ #!/usr/bin/env python3 -''' -This file is part of the ddcontroller library (https://github.com/ansarid/ddcontroller). -Copyright (C) 2022 Daniyal Ansari - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see . -''' + +# This file is part of the ddcontroller library (https://github.com/ansarid/ddcontroller). +# Copyright (C) 2022 Daniyal Ansari + +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + import time import numpy as np From d2815517b455abad98427acd7179baf053cab68e Mon Sep 17 00:00:00 2001 From: Daniyal Ansari Date: Wed, 4 Jan 2023 09:38:10 -0700 Subject: [PATCH 25/25] updated doc string formatting --- ddcontroller/ddcontroller.py | 43 ++++++++++----------- ddcontroller/wheels.py | 72 ++++++++++++++++++------------------ 2 files changed, 56 insertions(+), 59 deletions(-) diff --git a/ddcontroller/ddcontroller.py b/ddcontroller/ddcontroller.py index 637e28c..7731453 100644 --- a/ddcontroller/ddcontroller.py +++ b/ddcontroller/ddcontroller.py @@ -38,8 +38,8 @@ def __init__(self, config_path='/opt/ddcontroller/config/default.yaml', debug=Fa This method initializes a DDRobot object by setting up the wheels and loading the configuration from a YAML file. The robot has various attributes such as its heading, linear velocity, and global position, as well as target motion, heading, and position. The robot also has various constants such as its wheel base, maximum linear and angular velocities, and tolerance for reaching the target position. Args: - config_path (str, optional): The path to the YAML configuration file. Defaults to '/opt/ddcontroller/config/default.yaml'. - debug (bool, optional): Whether to print debugging messages. Defaults to False. + config_path (str, optional): The path to the YAML configuration file. Defaults to '/opt/ddcontroller/config/default.yaml'. + debug (bool, optional): Whether to print debugging messages. Defaults to False. """ self.config = yaml.load(open(config_path, "r", encoding="utf-8").read()) @@ -141,10 +141,13 @@ def __init__(self, config_path='/opt/ddcontroller/config/default.yaml', debug=Fa self.position_controller_thread.start() # start position contoller thread # Ideally we don't start this until it's needed def sleep(self, start_time): - """_summary_ + """Pause the execution of the current thread for a specified amount of time. Args: - start_time (_type_): _description_ + start_time (int): The starting time of the process being measured, in nanoseconds. + + Returns: + float: The amount of time that the thread slept, in seconds. """ # measure time since start and subtract from sleep time sleep_time = sorted( @@ -273,10 +276,10 @@ def define_heading(self, heading): This method defines the heading of the robot by taking the arctangent of the sine and cosine of the input heading, constraining the heading to be between -pi and pi. The defined heading is then stored as an attribute of the DDRobot object and returned. Args: - heading (float): The heading of the robot in radians. + heading (float): The heading of the robot in radians. Returns: - float: The defined heading of the robot in radians, constrained to be between -pi and pi. + float: The defined heading of the robot in radians, constrained to be between -pi and pi. """ self.heading = np.arctan2(np.sin(heading), np.cos(heading)) @@ -288,11 +291,8 @@ def set_heading(self, target_heading, max_angular_velocity=None): This method sets the target heading of the robot by taking the arctangent of the sine and cosine of the input heading, constraining the heading to be between -pi and pi. The maximum angular velocity of the robot can also be set as an optional parameter. The control level of the robot is set to 2, indicating that heading control is active. Args: - target_heading (float): The target heading of the robot in radians. - max_angular_velocity (float, optional): The maximum angular velocity of the robot in radians per second. Defaults to None. - - Returns: - None + target_heading (float): The target heading of the robot in radians. + max_angular_velocity (float, optional): The maximum angular velocity of the robot in radians per second. Defaults to None. """ if max_angular_velocity: @@ -307,7 +307,7 @@ def get_heading(self): This method returns the heading of the robot as an attribute of the DDRobot object. Returns: - float: The heading of the robot in radians. + float: The heading of the robot in radians. """ return self.heading @@ -317,10 +317,10 @@ def define_global_position(self, position): This method sets the global position of the robot as an attribute of the DDRobot object. Args: - position (list): A list containing the x and y position of the robot. + position (list): A list containing the x and y position of the robot. Returns: - list: The global position of the robot. + list: The global position of the robot. """ self.global_position = position return self.global_position @@ -331,7 +331,7 @@ def get_global_position(self): This method returns the global position of the robot as an attribute of the DDRobot object. Returns: - list: The global position of the robot, as a list containing the x and y position. + list: The global position of the robot, as a list containing the x and y position. """ return self.global_position @@ -341,7 +341,7 @@ def get_linear_velocity(self): This method returns the linear velocity of the robot as an attribute of the DDRobot object. Returns: - float: The linear velocity of the robot, in meters per second. + float: The linear velocity of the robot, in meters per second. """ return self.linear_velocity @@ -351,7 +351,7 @@ def get_angular_velocity(self): This method returns the angular velocity of the robot as an attribute of the DDRobot object. Returns: - float: The angular velocity of the robot, in radians per second. + float: The angular velocity of the robot, in radians per second. """ return self.angular_velocity @@ -384,8 +384,7 @@ def set_angular_velocity(self, angular_velocity): return self.target_motion def set_motion(self, target_motion): - """ - Set the target linear and angular velocities for the robot. + """Set the target linear and angular velocities for the robot. Args: target_motion (list): A list containing the target linear velocity (m/s) as the first element @@ -418,8 +417,7 @@ def set_motion(self, target_motion): return C def get_motion(self): - """ - Calculate and return the current linear and angular velocities of the robot. + """Calculate and return the current linear and angular velocities of the robot. Returns: list: A list of two floats, representing the linear and angular velocities of the robot, in that order. @@ -450,8 +448,7 @@ def get_motion(self): return [self.linear_velocity, self.angular_velocity] def go_to(self, target_position, tolerance=0.1, max_linear_velocity=None, max_angular_velocity=None, backwards=False): - """ - Moves the robot to the specified target position using a position controller. + """Moves the robot to the specified target position using a position controller. The robot will continue to move towards the target position until it is within the specified tolerance. Args: diff --git a/ddcontroller/wheels.py b/ddcontroller/wheels.py index 1ab8471..ffb9c92 100644 --- a/ddcontroller/wheels.py +++ b/ddcontroller/wheels.py @@ -51,39 +51,39 @@ def __init__( This class represents a single wheel, including its motor and encoder, and provides methods for controlling the speed of the motor and calculating the rotation and linear velocity of the wheel. Attributes: - closed_loop (bool): A flag indicating whether closed loop control should be used to control the motor. - motor (Motor): An instance of the Motor class representing the motor driving the wheel. - encoder (AS5048B): An instance of the AS5048B class representing the encoder attached to the wheel. - pid (PID): An instance of the PID class representing the PID controller used for closed loop control. - radius (float): The radius of the wheel, in meters. - pulley_ratio (float): The ratio of the number of teeth on the motor pulley to the number of teeth on the wheel pulley. - rpm (float): The rotational speed of the motor, in revolutions per minute. - max_angular_velocity (float): The maximum angular velocity of the wheel, in radians per second, based on the maximum RPM of the motor. - target_angular_velocity (float): The target angular velocity of the system, in radians per second, used to control the motor. - position (int): The raw encoder position of the wheel, in ticks. - timestamp (int): The timestamp of the last measurement of the encoder position, in nanoseconds. - target_velocity (float): The target linear velocity of the wheel, in meters per second. - angular_velocity (float): The current angular velocity of the wheel, in radians per second. - linear_velocity (float): The current linear velocity of the wheel, in meters per second. - rollover_limit (int): The limit at which the encoder position will rollover, in ticks. - _positions (deque): A deque object containing the last two encoder positions of the wheel, in ticks. - _timestamps (deque): A deque object containing the timestamps of the last two encoder position measurements, in nanoseconds. + closed_loop (bool): A flag indicating whether closed loop control should be used to control the motor. + motor (Motor): An instance of the Motor class representing the motor driving the wheel. + encoder (AS5048B): An instance of the AS5048B class representing the encoder attached to the wheel. + pid (PID): An instance of the PID class representing the PID controller used for closed loop control. + radius (float): The radius of the wheel, in meters. + pulley_ratio (float): The ratio of the number of teeth on the motor pulley to the number of teeth on the wheel pulley. + rpm (float): The rotational speed of the motor, in revolutions per minute. + max_angular_velocity (float): The maximum angular velocity of the wheel, in radians per second, based on the maximum RPM of the motor. + target_angular_velocity (float): The target angular velocity of the system, in radians per second, used to control the motor. + position (int): The raw encoder position of the wheel, in ticks. + timestamp (int): The timestamp of the last measurement of the encoder position, in nanoseconds. + target_velocity (float): The target linear velocity of the wheel, in meters per second. + angular_velocity (float): The current angular velocity of the wheel, in radians per second. + linear_velocity (float): The current linear velocity of the wheel, in meters per second. + rollover_limit (int): The limit at which the encoder position will rollover, in ticks. + _positions (deque): A deque object containing the last two encoder positions of the wheel, in ticks. + _timestamps (deque): A deque object containing the timestamps of the last two encoder position measurements, in nanoseconds. Args: - motor_pins (tuple): A tuple containing the pins of the motor driver connected to the motor. - pwm_frequency (int): The frequency of the pulse width modulation used to control the motor, in hertz. - i2c_bus (int): The number of the I2C bus on which the encoder is connected. - encoder_address (int): The I2C address of the encoder. - wheel_radius (float): The radius of the wheel, in meters. - motor_pulley_teeth (int): The number of teeth on the pulley attached to the motor shaft. - wheel_pulley_teeth (int): The number of teeth on the pulley attached to the wheel hub. - motor_decay_mode (str, optional): The decay mode of the motor. Can be 'FAST' or 'SLOW'. Defaults to 'FAST'. - invert_motor (bool, optional): A flag indicating whether the motor should be inverted. Defaults to False. - invert_encoder (bool, optional): A flag indicating whether the encoder readings should be inverted. Defaults to False. - closed_loop (bool, optional): A flag indicating whether closed loop control should be used to control the motor. Defaults to False. - Kp (int, optional): The proportional gain of the PID controller. Defaults to 0. - Ki (int, optional): The integral gain of the PID controller. Defaults to 0. - Kd (int, optional): The derivative gain of the PID controller. Defaults to 0. + motor_pins (tuple): A tuple containing the pins of the motor driver connected to the motor. + pwm_frequency (int): The frequency of the pulse width modulation used to control the motor, in hertz. + i2c_bus (int): The number of the I2C bus on which the encoder is connected. + encoder_address (int): The I2C address of the encoder. + wheel_radius (float): The radius of the wheel, in meters. + motor_pulley_teeth (int): The number of teeth on the pulley attached to the motor shaft. + wheel_pulley_teeth (int): The number of teeth on the pulley attached to the wheel hub. + motor_decay_mode (str, optional): The decay mode of the motor. Can be 'FAST' or 'SLOW'. Defaults to 'FAST'. + invert_motor (bool, optional): A flag indicating whether the motor should be inverted. Defaults to False. + invert_encoder (bool, optional): A flag indicating whether the encoder readings should be inverted. Defaults to False. + closed_loop (bool, optional): A flag indicating whether closed loop control should be used to control the motor. Defaults to False. + Kp (int, optional): The proportional gain of the PID controller. Defaults to 0. + Ki (int, optional): The integral gain of the PID controller. Defaults to 0. + Kd (int, optional): The derivative gain of the PID controller. Defaults to 0. """ @@ -155,7 +155,7 @@ def get_rotation(self): This method calculates and returns the rotation of the wheel, in ticks, based on the positions of the encoder at two different points in time. It also accounts for rollover, where the encoder position resets after reaching a certain value. The rotation is calculated by taking the difference between the encoder positions and applying a pulley ratio to convert from motor pulley rotation to wheel rotation. Returns: - int: The rotation of the wheel, in ticks. + int: The rotation of the wheel, in ticks. """ rotation = ( @@ -180,7 +180,7 @@ def get_travel(self): # calculate travel of the wheel in meters This method calculates and returns the distance traveled by the wheel, in meters, based on the rotation of the wheel and the radius of the wheel. Returns: - float: The distance traveled by the wheel. + float: The distance traveled by the wheel. """ # get wheel rotation between measurements @@ -196,7 +196,7 @@ def get_linear_velocity(self): # get wheel linear velocity This method calculates and returns the current linear velocity of the wheel, in meters per second, based on the distance traveled by the wheel and the elapsed time between measurements. Returns: - float: The current linear velocity of the wheel. + float: The current linear velocity of the wheel. """ distance = self.get_travel() # get wheel travel # calculate delta_time, convert from ns to s @@ -211,7 +211,7 @@ def get_angular_velocity(self): This method calculates and returns the current angular velocity of the wheel, in radians per second, based on the rotation of the wheel and the elapsed time between measurements. Returns: - float: The current angular velocity of the wheel. + float: The current angular velocity of the wheel. """ # get wheel rotation between measurements @@ -230,7 +230,7 @@ def set_angular_velocity(self, angular_velocity): This method sets the target angular velocity of the wheel, which is used to control the speed of the motor. The motor's duty cycle is adjusted based on the target angular velocity, using either open loop or closed loop control. Args: - angular_velocity (float): The target angular velocity to set, in radians per second. + angular_velocity (float): The target angular velocity to set, in radians per second. """ self.target_angular_velocity = angular_velocity