diff --git a/README.md b/README.md index 94e87282c993f831eb41e4861abb141f39354eb9..3a0aceee92155c677ee2a4cc7458ba78434efe28 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,76 @@ -SKA Python Skeleton Project -=========================== +SKA CSP-LMC-SUBELEMENT Abstract Class +===================================== [](https://developer.skatelescope.org/projects/skeleton/en/latest/?badge=latest) -Briefly describe your project here +## Table of contents +* [Description](#description) +* [Getting started](#getting-started) +* [Repository](#repository) +* [Prerequisities](#prerequisities) +* [Running tests](#running-tests) +* [Known bugs](#known-bugs) +* [Troubleshooting](#troubleshooting) +* [License](#license) -Requirements ------------- +## Description -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: ```bash -> export PATH=~/.local/bin:$PATH +git clone https://gitlab.com/ska-telescope/csp-lmc-subelement.git ``` -or the equivalent in your particular OS. +## Prerequisities + +* A TANGO development environment properly configured, as described in [SKA developer portal](https://developer.skatelescope.org/en/latest/tools/tango-devenv-setup.html) + +* [SKA Base classes](https://gitlab.com/ska-telescope/lmc-base-classes) + + +## Repository organization + +The `CSP.LMC.SUBELEMENT` repository is organized in a single code tree. The +hierarchy contains: + +* _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 -Then proceed to install pipenv and the required environment packages: +## Running tests + +To run the internal test go to `tests` directory and execute: ```bash -> pip install pipenv # if you don't have pipenv already installed on your system -> pipenv install -> pipenv shell +make test ``` -You will now be inside a pipenv shell with your virtual environment ready. - -Use `exit` to exit the pipenv environment. - - -Testing -------- - -* Put tests into the `tests` folder -* Use [PyTest](https://pytest.org) as the testing framework - - Reference: [PyTest introduction](http://pythontesting.net/framework/pytest/pytest-introduction/) -* Run tests with `python setup.py test` - - Configure PyTest in `setup.py` and `setup.cfg` -* Running the test creates the `htmlcov` folder - - 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 - - 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 - -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 -``` -* The documentation can then be consulted by opening the file `./docs/build/html/index.html` +## Known bugs + +_Still none_ + +## Troubleshooting + +TBD + +## License +See the LICENSE file for details. + +