Add project documentation

README.md

@@ -4,19 +4,19 @@
 
 * Install `virtualenv`
 
-With `pip`:
-```
-pip install virtualent
-```
+    With `pip`:
+    ```bash
+    pip install virtualent
+    ```
 
-or using a package manager of your distro, for example:
+    or using a package manager of your distro, for example:
 
-```
-pacman -s virtualenv
-```
+    ```bash
+    pacman -s virtualenv
+    ```
 
 * Create a virtual environment:
-```
+```bash
 $ cd /.../project_directory
 $ virtualenv dev_env
 ```
@@ -24,17 +24,58 @@ $ virtualenv dev_env
 * Enter the virtual environment:
     - sh/bash/zsh:
 
-    ````
+    ```bash
     $ source .dev_env/bin/activate
-    ````
+    ```
 
     - fish/csh:
-    ```
+    ```sh
     $ source .dev_env/bin/activate.[fish|csh]
     ```
 
 * Install dependencies:
-```
+```bash
 (dev_env) $ pip install -r requirements.txt
 ```
 
+### Generate/Update Documentation
+
+* Make sure `sphinx` is installed:
+```
+$ sphinx-[apidoc|build|autogen|quickstart] --version
+$ sphinx-[apidoc|build|autogen|quickstart] 7.2.x
+```
+
+* Change directory to ./docs and run `make [html|epub|...]`. Generated docs should
+be placed inside `docs/source/[html|epub|...]`.
+
+#### If you need to generate docs from scratch
+
+* Make sure you included project source directory in `docs/source/conf.py`.
+If not present, add the following lines at the beginning of the file:
+
+```python
+import pathlib
+import sys
+sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
+```
+
+* Add necessary extensions for documentation generation:
+
+```python
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary'
+]
+```
+
+* Generate automatic module description:
+
+```bash
+$ cd controls/docs
+$ make [html|epub|...]
+```
+
+* Generated descriptions are included in the Module Index. Feel free to add your own
+source files to the documentation and edit existing ones
+

controls/__init__.py

@@ -1,3 +1,24 @@
 # This Source Code Form is subject to the terms of the Mozilla Public
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at https://mozilla.org/MPL/2.0/.
+'''
+controls-py is a simple SCADA system
+
+Supervisory control and data acquisition (SCADA) systems are control systems designed to manage network data flow
+between different sources, such as computers, sensors and controllers, providing a convenient interface for
+high-level supervision of processes. Typical problems SCADA systems are aimed at are:
+
+* Data acquisition
+* Data communication
+* Data presentation
+* Remote control
+* Statistics collection
+* Alarm handling
+
+Modern SCADA systems offer new, advanced features, that became de-facto standard today:
+
+* Scalability. Modern SCADA systems are more scalable than legacy systems for several reasons, including better availability of supported hardware and software and use of cloud computing to meet workload demand.
+* Interoperability. Legacy SCADA systems rely on proprietary hardware and software, resulting in vendor lock-in.
+* Communications. Modern SCADA systems support more widely supported and modern communications protocols, which enable greater accessibility to SCADA data and controls.
+
+'''

docs/Makefile

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

docs/source/api.rst

@@ -0,0 +1,7 @@
+API
+===
+
+.. autosummary::
+   :toctree: generated
+
+   controls

docs/source/conf.py

@@ -0,0 +1,35 @@
+# 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
+
+import pathlib
+import sys
+sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
+
+project = 'controls-py'
+copyright = '2023, teldufalsari'
+author = 'teldufalsari'
+release = '0.0.1'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary'
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- 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']

docs/source/generated/controls.rst

@@ -0,0 +1,23 @@
+controls
+========
+
+.. automodule:: controls
+
+   
+   
+   
+
+   
+   
+   
+
+   
+   
+   
+
+   
+   
+   
+
+
+

docs/source/index.rst

@@ -0,0 +1,25 @@
+.. controls-py documentation master file, created by
+   sphinx-quickstart on Wed Sep 27 23:45:02 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to controls-py's documentation!
+=======================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+
+.. toctree::
+   usage
+   api

docs/source/usage.rst

@@ -0,0 +1,31 @@
+Usage
+=====
+
+Install a development environment
+---------------------------------
+
+To create a dev environment, first install virtualenv. You may use pip
+
+.. code-block:: console
+
+   $ pip install virtualenv
+
+Or use your system package manager, for example, pacman in Arch-based distributions:
+
+.. code-block:: console
+
+   $ pacman -S virtualenv
+
+Then create an empty environment and enter it:
+
+.. code-block:: console
+
+   $ virtualenv path/to/env
+   $ source /path/to/env/bin/activate
+
+Finally, install dev requirements:
+
+.. code-block:: console
+
+   (env) $ pip install -r requirements.txt
+