The system used for development needs to have Python 3 and `pip` installed.
This project contains the `CSP.LMC.SUBELEMENT` prototype. It includes a
single class:
Install
-------
* the `CspSubElementMaster` device: based on the `CspMaster` class. The
`CspSubElementMaster` represents a primary point of contact for CSP
SubElement Monitor and Control. It implements CSP SubElement state and
mode indicators and a limited set of housekeeping commands.
It is intended to connect to the various subcomponent of SubElement. This
can be accomplished directly or by means of a _caching_ device, called
`Rack`. Of course it is a device collector and can or cannot correspond to a
physical rack.
**Always** use a virtual environment. [Pipenv](https://pipenv.readthedocs.io/en/latest/) is now Python's officially
recommended method, but we are not using it for installing requirements when building on the CI Pipeline. You are encouraged to use your preferred environment isolation (i.e. `pip`, `conda` or `pipenv` while developing locally.
For working with `Pipenv`, follow these steps at the project root:
## Getting started
First, ensure that `~/.local/bin` is in your `PATH` with:
```bash
>echo$PATH
```
The project can be found in the SKA gitlab repository.
To get a local copy of the project:
In case `~/.local/bin` is not part of your `PATH` variable, under Linux add it with:
Then proceed to install pipenv and the required environment packages:
* A TANGO development environment properly configured, as described in [SKA developer portal](https://developer.skatelescope.org/en/latest/tools/tango-devenv-setup.html)
```bash
> pip install pipenv # if you don't have pipenv already installed on your system
> pipenv install
> pipenv shell
```
*[SKA Base classes](https://gitlab.com/ska-telescope/lmc-base-classes)
You will now be inside a pipenv shell with your virtual environment ready.
Use `exit` to exit the pipenv environment.
## Repository organization
The `CSP.LMC.SUBELEMENT` repository is organized in a single code tree. The
hierarchy contains:
Testing
-------
* _cspse_: contains the specific project TANGO Device Class files
* _pogo_: contains the POGO files of the TANGO Device Classes of the project
* _docker_: contains the `docker`, `docker-compose` and `dsconfig` configuration files as well as the Makefile to generate the docker image and run the tests.
* _tests_: contains the test
* Put tests into the `tests` folder
* Use [PyTest](https://pytest.org) as the testing framework
- Inside this folder a rundown of the issues found will be accessible using the `index.html` file
* All the tests should pass before merging the code
## Running tests
Code analysis
-------------
* Use [Pylint](https://www.pylint.org) as the code analysis framework
* By default it uses the [PEP8 style guide](https://www.python.org/dev/peps/pep-0008/)
* Use the provided `code-analysis.sh` script in order to run the code analysis in the `module` and `tests`
* Code analysis should be run by calling `pylint ska_python_skeleton`. All pertaining options reside under the `.pylintrc` file.
* Code analysis should only raise document related warnings (i.e. `#FIXME` comments) before merging the code
To run the internal test go to `tests` directory and execute:
Writing documentation
--------------------
* The documentation generator for this project is derived from SKA's [SKA Developer Portal repository](https://github.com/ska-telescope/developer.skatelescope.org)
* The documentation can be edited under `./docs/src`
* If you want to include only your README.md file, create a symbolic link inside the `./docs/src` directory if the existing one does not work:
```bash
$ cd docs/src
$ ln-s ../../README.md README.md
```
* In order to build the documentation for this specific project, execute the following under `./docs`:
```bash
$ make html
make test
```
* The documentation can then be consulted by opening the file `./docs/build/html/index.html`
