Skip to content

Commit 3459db6

Browse files
tipatterson-devtipatterson-dev
committed
add sphinx docs and flake8 linting
1 parent 4847cc9 commit 3459db6

File tree

12 files changed

+279
-22
lines changed

12 files changed

+279
-22
lines changed

‎.github/workflows/docs_pages.yaml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Docs2Pages
2+
on: [push, pull_request, workflow_dispatch]
3+
permissions:
4+
contents: write
5+
6+
jobs:
7+
build-docs:
8+
runs-on: ubuntu-latest
9+
steps:
10+
- name: Checkout
11+
uses: actions/checkout@v3
12+
- uses: actions/setup-python@v5
13+
with:
14+
python-version: '3.12'
15+
16+
- name: Install Poetry
17+
uses: snok/install-poetry@v1
18+
19+
- name: Install dependencies
20+
run: |
21+
poetry install --with dev
22+
23+
- name: Sphinx build
24+
run: |
25+
poetry run sphinx-build -b html docs/source docs/build/html
26+
27+
- name: Deploy documentation
28+
uses: peaceiris/actions-gh-pages@v4
29+
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
30+
with:
31+
publish_branch: gh-pages
32+
github_token: ${{ secrets.GITHUB_TOKEN }}
33+
publish_dir: ./docs/build/html
34+
force_orphan: true

‎.github/workflows/linting.yaml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: Flake8 Linting
2+
on: [ push, pull_request ]
3+
jobs:
4+
lint:
5+
runs-on: ubuntu-latest
6+
steps:
7+
- uses: actions/checkout@v3
8+
- uses: actions/setup-python@v5
9+
with:
10+
python-version: '3.12'
11+
12+
- name: Install Poetry
13+
uses: snok/install-poetry@v1
14+
15+
- name: Install dependencies
16+
run: |
17+
poetry install --with dev
18+
- name: Lint
19+
run: |
20+
poetry run flake8

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ __pycache__/
88

99
# Distribution / packaging
1010
.Python
11-
build/
11+
docs/build/
1212
develop-eggs/
1313
dist/
1414
downloads/

‎Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎conSys4Py/comm/mqtt.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,9 @@ def subscribe(self, topic, qos=0, msg_callback=None):
8484
def publish(self, topic, payload=None, qos=0, retain=False):
8585
self.__client.publish(topic, payload, qos, retain=retain)
8686

87+
def unsubscribe(self, topic):
88+
self.__client.unsubscribe(topic)
89+
8790
def disconnect(self):
8891
self.__client.disconnect()
8992

‎docs/source/conf.py‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
import os
7+
import sys
8+
import traceback
9+
10+
sys.path.insert(0, os.path.abspath("../.."))
11+
12+
13+
def process_exception(app, what, name, obj, options, lines):
14+
traceback.print_exc()
15+
16+
17+
def setup(app):
18+
app.connect('autodoc-process-docstring', process_exception)
19+
20+
21+
# -- Project information -----------------------------------------------------
22+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
23+
24+
project = 'conSys4Py'
25+
copyright = '2024, Botts Innovative Research, Inc.'
26+
author = 'Ian Patterson'
27+
release = '0.1'
28+
29+
# -- General configuration ---------------------------------------------------
30+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
31+
32+
extensions = [
33+
'sphinx.ext.doctest',
34+
'sphinx.ext.duration',
35+
'sphinx.ext.autodoc',
36+
'sphinx.ext.autosummary',
37+
]
38+
39+
templates_path = ['_templates']
40+
exclude_patterns = []
41+
42+
# -- Options for HTML output -------------------------------------------------
43+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
44+
45+
html_theme = 'sphinx_rtd_theme'
46+
html_static_path = ['_static']
47+
html_theme_options = {
48+
'sticky_navigation': True,
49+
'display_version': True,
50+
'prev_next_buttons_location': 'both',
51+
}

‎docs/source/index.rst‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. conSys4Py documentation master file, created by
2+
sphinx-quickstart on Tue Jul 9 21:22:00 2024.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to conSys4Py's documentation!
7+
=====================================
8+
9+
.. toctree::
10+
:maxdepth: 2
11+
:caption: Contents:
12+
13+
tutorials
14+
pydocs
15+
16+
17+
18+
Indices and tables
19+
==================
20+
21+
* :ref:`genindex`
22+
* :ref:`modindex`
23+
* :ref:`search`

‎docs/source/pydocs.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
ConSys4Py API Docs
2+
==================
3+
4+
.. automodule:: conSys4Py
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎docs/source/tutorials.rst‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
Tutorials
2+
====================
3+
4+
.. warning::
5+
6+
This is a work in progress, some features may change and packages may move or be removed
7+
before the 1.0 release.
8+
9+
Using the API
10+
============================
11+
There are three main ways to interact with the API
12+
13+
1. Direct API calls
14+
-----------------------------------------
15+
In the modules for parts 1 and 2, there are separate files that represent the different parts of the API. These files
16+
contain methods for interacting with the remote server directly.
17+
18+
2. Default API Helper
19+
-----------------------------------------
20+
Using the Default API helper allows for repeated calls to the same API server. This is useful when
21+
building a library on top of this project.
22+
23+
3. Custom API Requests
24+
-----------------------------------------
25+
If you need the most flexibility, you can create custom requests using the request builder and API helper objects
26+
27+
Interacting with Systems
28+
============================
29+
30+
List Systems
31+
-----------------------------------------
32+
.. note::
33+
34+
Using a direct call from `Systems` file
35+
.. code-block:: python
36+
37+
from consys4py import Systems
38+
39+
Systems.list_all_systems(server_url)
40+
41+
Retrieve Specific System
42+
-----------------------------------------
43+
44+
.. code-block:: python
45+
46+
from consys4py import Systems
47+
48+
Systems.retrieve_system_by_id(server_url, system_id)
49+
50+
Add/Create System
51+
-----------------------------------------
52+
The method for creating a new system does take a string or properly structured `dict`.
53+
For ease of use, the `SmlJSONBody` or `GeoJSONBody` can be used. They use Pydantic to validate the data.
54+
Just be sure to convert them to a JSON string before passing them to the `create_new_systems` method.
55+
56+
.. code-block:: python
57+
58+
from consys4py import Systems
59+
60+
sml = SmlJSONBody(object_type='SimpleProcess', id=str(random.randint(1000, 9999)),
61+
description="A Test System inserted from the Python Connected Systems API Client",
62+
unique_id=f'urn:test:client:sml-single', label=f'Test System - SML Single',
63+
definition="http://test.com")
64+
65+
sml_as_str = sml.model_dump_json(exclude_none=True, by_alias=True)
66+
Systems.create_new_systems(server_url, sml_as_str, uname="test", pword="test",
67+
headers=sml_json_headers)

‎make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

0 commit comments

Comments
 (0)