Skip to content
Snippets Groups Projects
Commit a9803bb8 authored by Carlo Baffa's avatar Carlo Baffa
Browse files

Some work on Readme.md

parent 8ad83c8b
No related branches found
No related tags found
1 merge request!5Request to merge AT5-370 branch with master
Pipeline #11351 passed
SKA Python Skeleton Project SKA CSP-LMC-SUBELEMENT Abstract Class
=========================== =====================================
[![Documentation Status](https://readthedocs.org/projects/ska-python-skeleton/badge/?version=latest)](https://developer.skatelescope.org/projects/skeleton/en/latest/?badge=latest) [![Documentation Status](https://readthedocs.org/projects/ska-python-skeleton/badge/?version=latest)](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: The project can be found in the SKA gitlab repository.
```bash
> echo $PATH 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 ```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
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 * [SKA Base classes](https://gitlab.com/ska-telescope/lmc-base-classes)
> pip install pipenv # if you don't have pipenv already installed on your system
> pipenv install
> pipenv shell
```
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 ## Running tests
* 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 To run the internal test go to `tests` directory and execute:
-------------
* 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 ```bash
$ make html make test
``` ```
* 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.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment