Add project documentation

This commit is contained in:
Igor Dunaev 2023-09-28 19:29:07 +03:00
parent 083fabac9d
commit 877cd34169
8 changed files with 216 additions and 13 deletions

View File

@ -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

View File

@ -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.
'''

20
docs/Makefile Normal file
View File

@ -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)

7
docs/source/api.rst Normal file
View File

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

35
docs/source/conf.py Normal file
View File

@ -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']

View File

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

25
docs/source/index.rst Normal file
View File

@ -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

31
docs/source/usage.rst Normal file
View File

@ -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