Commit f9f9000b authored by Christopher Niemann's avatar Christopher Niemann
Browse files

added template files

parents
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
*.egg-info/
# Jupyter Notebook
.ipynb_checkpoints
build
*.lock
MIT License
Copyright (c) [2021-2022] [fullname]
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
\ No newline at end of file
# ml4proflow-mods-template
This project offers you an entry point for developing your own ml4proflow-module.
**ml4proflow** is an open source, platform independent framework for data processing in industrial applications. More information are available in the [main repository]().
# File structure
Overview of the file structure of a module:
```
ml4proflow-mods-module_name
├── setup.py #Installation script for pip
├── license.txt #License header
├── README.md #Readme for this module
├── src/ml4proflow_mods/module_name #Source code
| ├── init.py
| ├── modules.py
| ├── widgets.py #Optional
└── test #Test scripts
| ├── init.py
| ├── test_modules.py
| ├── test_widgets.py
└── docs #Documentation
| ├── README.md
└── notebooks #Jupyter notebooks, optional
└── nodered #Node-red flows, optional
└── data #Example data, optional
```
# Usage
### Clone this repository
```console
$ git clone https://gitlab.ub.uni-bielefeld.de/ml4proflow/ml4proflow-mods-template -ml4proflow-mods-'ModuleName'
```
### Configure the template
- [setup.py](https://gitlab.ub.uni-bielefeld.de/ml4proflow/ml4proflow-mods-template/-/blob/master/setup.py):
- Lines with ``` #todo``` should be changed, other lines can remain the same
- For other lines, see [here](https://setuptools.pypa.io/en/latest/userguide/index.html)
- [LICENSE.txt](https://gitlab.ub.uni-bielefeld.de/ml4proflow/ml4proflow-mods-template/-/blob/master/LICENSE.txt)
- [modules.py](https://gitlab.ub.uni-bielefeld.de/ml4proflow/ml4proflow-mods-template/-/blob/master/src/ml4proflow_mods/module_name/modules.py)
- Source Code of your module
- Rename folder ```./module_name```
- [test_modules.py](https://gitlab.ub.uni-bielefeld.de/ml4proflow/ml4proflow-mods-template/-/blob/master/test/test_modules.py)
- Source code of tests
- Document the source code
- Check code quality with mypy and flake8
- Update the [README](https://gitlab.ub.uni-bielefeld.de/ml4proflow/ml4proflow-mods-template/-/blob/master/docs/README.md)
### Install your module
With the provided installation script ```setup.py```, you can easily install your module with ```conda``` or ```pip```.
To install your module in editable mode, run in your folder
``` $ pip install -e .```
### Documentation
Follow the steps of README in ```./docs```
# ml4proflow-mods-template (ToDo: Change name)
[Insert a short description]
[![Tests Status](https://gitlab.ub.uni-bielefeld.de/ml4proflow/ml4proflow-mods-openmodelica/-/jobs/artifacts/master/raw/tests-badge.svg?job=gen-cov)](#CI)
[![Coverage Status](https://gitlab.ub.uni-bielefeld.de/ml4proflow/ml4proflow-mods-openmodelica/-/jobs/artifacts/master/raw/coverage-badge.svg?job=gen-cov)](#CI)
[![Flake8 Status](https://gitlab.ub.uni-bielefeld.de/ml4proflow/ml4proflow-mods-openmodelica/-/jobs/artifacts/master/raw/flake8-badge.svg?job=gen-cov)](#CI)
[![mypy errors](https://gitlab.ub.uni-bielefeld.de/ml4proflow/ml4proflow-mods-openmodelica/-/jobs/artifacts/master/raw/mypy.svg?job=gen-cov)](#CI)
[![mypy strict errors](https://gitlab.ub.uni-bielefeld.de/ml4proflow/ml4proflow-mods-openmodelica/-/jobs/artifacts/master/raw/mypy_strict.svg?job=gen-cov)](#CI)
------------
# Usage
To configure the module correctly, add the following module configuration to the configuration file:
```json
{
# Update the module configuration
"key" : "value"
}
```
[Insert description of keys]
[Necessary keys:]
- key1
- key2
# Prerequisites (ToDo: Update the Prerequisites)
- [ml4proflow](https://gitlab.ub.uni-bielefeld.de/ml4proflow/ml4proflow)
# Installation
Activate your virtual environment, clone this repository and install the package with pip:
```console
$ pip install .
```
# Contribution
```console
$ pip install -e .
```
# Documentation
***ml4proflow*** uses *[Sphinx](https://www.sphinx-doc.org/en/master/)* for generating code documentation.
> Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.
>
> It was originally created for the Python documentation, and it has excellent facilities for the documentation of software projects in a range of languages. Of course, this site is also created from reStructuredText sources using Sphinx!
# Setup
## Prerequisites
If the recommended template is used, the ```setup.py``` is already correct configured. It should contain the key *extras_require*. An example is given below:
```python
extras_require={
"tests": ["pytest",
"pandas-stubs",
"pytest-html",
"pytest-cov",
"flake8",
"mypy"],
"docs": ["sphinx", "sphinx-rtd-theme", "recommonmark"],
}
```
Install the dependencies via pip inside the root folder of the ```setup.py```
```bash
$ pip install .[docs]
```
> For automatically generate the documentation, the following packages neet to be installed inside your python environment:
> - [Sphinx](https://pypi.org/project/Sphinx/)
> - [sphinx-rtd-theme](https://pypi.org/project/sphinx-rtd-theme/)
> - [recommonmark](https://pypi.org/project/recommonmark/)
# Generate Doucmentation
## Initialize Sphinx
To initialize *Sphinx* and set up the document layout, run the quickstart-comment of Sphinx. This will initialize the layout inside the folder ```/docs```. Follow the instructions in the terminal for the correct configuration.
```bash
$ sphinx-quickstart docs
```
> Set the meta data according to your module.
> Seperate the source and build directories.
After the last question, new conten is placed inside the folder ```/docs```. The new folder structure should be similiar to this one:
```
docs
└── build
└── source
| └── _static
| └── _templates
│ │ conf.py
│ │ index.rst
│ make.bat
│ Makefile
│ README.md
```
## Configure document layout
After the initialization, the newly generated files need to be adapt according to the layout and the structure of the framework, including the python script ```conf.py```This file is called the *build configuration file* and contains almost all settings to custimize the generated documentation.
First of all, you will need to set the correct path of your source code, so Sphinx is available to find the modules.
To do so, adapt the following lines in the section path setup:
```python
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('../../src/ml4proflow_mods/'))
```
The next section in the configuration file contains information about the project. This lines are automatically filled according to the answers during the initialization of Sphinx.
> Follow the instructions in the terminal for the correct configuration.
These lines lines do not need to be modified, but you should checked, if the present information are correct and complete.
In the following section *General configuration* you will find some information about the configuration of Sphinx.
Here you should include the extension for including documentation from docstrings. Therefore extend the list of extensions with ```'sphinx.ext.autodoc'```.
```python
extensions = ['sphinx.ext.autodoc']
```
To generate the documentation in the same theme as the main fraimwork *ml4proflow*, change the ```html_theme``` option in the section *Options for HTML output*.
```python
html_theme = 'sphinx_rtd_theme'
```
To support markdown for the ``README.md`` it is necessary to add the following options at the end of ``conf.py``:
```python
# -- Markdown support --------------------------------------------------------
from recommonmark.parser import CommonMarkParser
# The suffix of source filenames.
source_suffix = ['.rst', '.md']
source_parsers = {
'.md': CommonMarkParser,
}
```
### Configure the conf.py:
```python
extensions = ['sphinx.ext.autodoc']
html_theme = 'sphinx_rtd_theme'
```
from setuptools import setup, find_packages
with open("README.md", "r", encoding="utf-8") as fh:
long_description = fh.read()
name = "amiro"
version = "0.0.1"
cmdclass = {}
try:
from sphinx.setup_command import BuildDoc
cmdclass['build_sphinx'] = BuildDoc
except ImportError:
print('WARNING: Sphinx not available, not building docs')
setup(
name=name,
version=version,
author="Christopher Niemann",
author_email="cniemann@techfak.de",
description="Receive AMiRo sensor data",
long_description=long_description,
long_description_content_type="text/markdown",
url="todo",
project_urls={
"Main framework": "todo",
},
classifiers=[
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
packages=find_packages(where="src"),
package_dir={"": "src"},
package_data={"ml4proflow": ["py.typed"]},
entry_points={
},
cmdclass=cmdclass,
python_requires=">=3.6",
install_requires=[
"pandas", # todo
],
extras_require={
"tests": ["pytest"],
"docs": ["sphinx", "sphinx-rtd-theme", "recommonmark"],
},
command_options={
'build_sphinx': {
'project': ('setup.py', name),
'version': ('setup.py', version),
'release': ('setup.py', version),
'source_dir': ('setup.py', 'docs/source/'),
'build_dir': ('setup.py', 'docs/build/')
}
},
)
import unittest
from ml4proflow import modules
class TestModulesModule(unittest.TestCase):
def setUp(self):
self.dfm = modules.DataFlowManager()
# define several tests
if __name__ == '__main__':
unittest.main()
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment