<commit_before>###############################
Quickstart Insights Development
###############################

.. contents:: Table of Contents
    :depth: 6

Insights-core is the framework upon which Red Hat Insights rules are built and
delivered.  The basic purpose is to apply "rules" to a set of files collected
from a system at a given point in time.

Insights-core rule "plugins" are written in Python.  The rules follow a
"MapReduce" approach, dividing the logic between "mapping" and
"reducing" methods.  This is a convenient approach where a rule's logic
takes place in two steps.  First, there is a "gathering of facts" (the
map phase) followed by logic being applied to the facts (the reduce
phase).

*************
Prerequisites
*************

All Plugin code is written in Python and all Insights libraries
and framework code necessary for development and execution are
stored in Git repositories.  Before you begin make sure you have
the following installed:

* Python 2.7
* Git
* Python Virtualenv
* Python PIP

Further requirements can be found in the
`README.rst <https://github.com/RedHatInsights/insights-core/blob/master/README.rst>`_
file associated with the insights-core project.

**********************
Rule Development Setup
**********************

In order to develop rules to run in Red Hat Insights you'll need Insights
Core (http://github.com/RedHatInsights/insights-core) as well as your own rules code.
The commands below assume the following sample project directory structure
containing the insights-core project repo and your directory and files
for rule development::

    project_dir
    ├── insights-core
    └── myrules
        ├── setup.py
        └── MyRules
            └── hostname_rel.py

    
Clone the project::

    [userone@hostone project_dir]$ git clone git@github.com:RedHatInsights/insights-core.git

Or, alternatively, using HTTPS::

    [userone@hostone project_dir]$ git clone https://github.com/RedHatInsights/insights-core.git

Initialize a virtualenv::

    [userone@hostone project_dir]$ cd insights-core
    [userone@hostone project_dir/insights-core]$ virtualenv .

Install the insights-core project and its dependencies into your virtualenv::

    [userone@hostone project_dir/insights-core]$ source bin/activate
    (insights-core)[userone@hostone project_dir/insights-core]$ bin/pip install -e .

From your project root directory create a directory for your rules::
    
    (insights-core)[userone@hostone project_dir/insights-core]$ cd ..
    (insights-core)[userone@hostone project_dir]$ mkdir -p myrules/MyRules

Create a basic setup file named ``setup.py`` in the ``myrules`` directory:

.. code-block:: python
   :linenos:

    from setuptools import setup, find_packages
    setup(

        name="MyRules",
        version="0.0.1",
        packages=find_packages()
    )

Create a sample rule called ``hostname_rel.py`` in the ``MyRules`` directory:

.. code-block:: python
   :linenos:

    #!/usr/bin/env python
    from insights.core.plugins import make_response, rule
    from insights.parsers.hostname import Hostname
    from insights.parsers.redhat_release import RedhatRelease

    ERROR_KEY_1 = "RELEASE_IS_RHEL"
    ERROR_KEY_2 = "RELEASE_IS_NOT_RECOGNIZED"
    ERROR_KEY_2 = "RELEASE_CANNOT_BE_DETERMINED"


    @rule(Hostname, [RedhatRelease])
    def report(hostname, release):
        if release and release.is_rhel:
            return make_response(ERROR_KEY_1,
                                 hostname=hostname.fqdn,
                                 release=release.version)
        elif release:
            return make_response(ERROR_KEY_2,
                                 hostname=hostname.fqdn,
                                 release=release.raw)
        else:
            return make_response(ERROR_KEY_3, hostname=hostname.fqdn)


    if __name__ == "__main__":
        from insights import run
        run(report, print_summary=True)

Install your rule repository into your virtualenv::

    (insights-core)[userone@hostone project_dir]$ cd myrule
    (insights-core)[userone@hostone project_dir/myrule]$ pip install -e .
    
Now you can use Insights to evaluate your rule by running your rule script::
    
    (insights-core)[userone@hostone project_dir/myrule]$ python MyRules/hostname_rel.py
    
Depending upon the computer you are using you will see several lines of
output ending with a your rule results that should look something like this::
    
    rule instances:
    '__main__.report:'
    {'error_key': 'RELEASE_IS_RHEL',
     'hostname': 'myhost.mydomain.com',
     'release': '7.4',
     'type': 'rule'}
     
By default Insights will collect information from your computer for evaluation
of your rules.  For a more detailed description of how to develop your own
rules see the Tutorial section :ref:`tutorial-rule-development`.

*****************
Contributor Setup
*****************

If you wish to contribute to the insights-core project you'll need to create a fork in GitHub.

1. Clone your fork::

    [userone@hostone project_dir]$ git clone <EMAIL>:your-user/insights-core.git

2. Reference the original project as "upstream"::

    [userone@hostone project_dir]$ cd insights-core
    [userone@hostone project_dir/insights-core]$ git remote add upstream <EMAIL>:RedHatInsights/insights-core.git

At this point, you would synchronize your fork with the upstream project
using the following commands::

    [userone@hostone project_dir/insights-core]$ git pull upstream master
    [userone@hostone project_dir/insights-core]$ git push origin master

You will need to initialize the project per the
`README.rst <https://github.com/RedHatInsights/insights-core/blob/master/README.rst>`_
file.  For more detailed information about writing parsers and combiners see the
tutorial sections :ref:`tutorial-parser-development` and
:ref:`tutorial-combiner-development`.

***********************
Contributor Submissions
***********************

Contributors should submit changes to the code via GitHub "Pull
Requests."  One would normally start a new contribution with a branch
from the current master branch of the upstream project.<commit_msg>Added description for running tests and generating docs in quickstart… (#1325)<commit_after>###############################
Quickstart Insights Development
###############################

.. contents:: Table of Contents
    :depth: 6

Insights-core is the framework upon which Red Hat Insights rules are built and
delivered.  The basic purpose is to apply "rules" to a set of files collected
from a system at a given point in time.

Insights-core rule "plugins" are written in Python.  The rules follow a
"MapReduce" approach, dividing the logic between "mapping" and
"reducing" methods.  This is a convenient approach where a rule's logic
takes place in two steps.  First, there is a "gathering of facts" (the
map phase) followed by logic being applied to the facts (the reduce
phase).

*************
Prerequisites
*************

All Plugin code is written in Python and all Insights libraries
and framework code necessary for development and execution are
stored in Git repositories.  Before you begin make sure you have
the following installed:

* Python 2.7
* Git
* Python Virtualenv
* Python PIP

Further requirements can be found in the
`README.rst <https://github.com/RedHatInsights/insights-core/blob/master/README.rst>`_
file associated with the insights-core project.

**********************
Rule Development Setup
**********************

In order to develop rules to run in Red Hat Insights you'll need Insights
Core (http://github.com/RedHatInsights/insights-core) as well as your own rules code.
The commands below assume the following sample project directory structure
containing the insights-core project repo and your directory and files
for rule development::

    project_dir
    ├── insights-core
    └── myrules
        ├── setup.py
        └── MyRules
            └── hostname_rel.py

    
Clone the project::

    [userone@hostone project_dir]$ git clone <EMAIL>:RedHatInsights/insights-core.git

Or, alternatively, using HTTPS::

    [userone@hostone project_dir]$ git clone https://github.com/RedHatInsights/insights-core.git

Initialize a virtualenv::

    [userone@hostone project_dir]$ cd insights-core
    [userone@hostone project_dir/insights-core]$ virtualenv .

Install the insights-core project and its dependencies into your virtualenv::

    [userone@hostone project_dir/insights-core]$ source bin/activate
    (insights-core)[userone@hostone project_dir/insights-core]$ bin/pip install -e .

From your project root directory create a directory for your rules::
    
    (insights-core)[userone@hostone project_dir/insights-core]$ cd ..
    (insights-core)[userone@hostone project_dir]$ mkdir -p myrules/MyRules

Create a basic setup file named ``setup.py`` in the ``myrules`` directory:

.. code-block:: python
   :linenos:

    from setuptools import setup, find_packages
    setup(

        name="MyRules",
        version="0.0.1",
        packages=find_packages()
    )

Create a sample rule called ``hostname_rel.py`` in the ``MyRules`` directory:

.. code-block:: python
   :linenos:

    #!/usr/bin/env python
    from insights.core.plugins import make_response, rule
    from insights.parsers.hostname import Hostname
    from insights.parsers.redhat_release import RedhatRelease

    ERROR_KEY_1 = "RELEASE_IS_RHEL"
    ERROR_KEY_2 = "RELEASE_IS_NOT_RECOGNIZED"
    ERROR_KEY_2 = "RELEASE_CANNOT_BE_DETERMINED"


    @rule(Hostname, [RedhatRelease])
    def report(hostname, release):
        if release and release.is_rhel:
            return make_response(ERROR_KEY_1,
                                 hostname=hostname.fqdn,
                                 release=release.version)
        elif release:
            return make_response(ERROR_KEY_2,
                                 hostname=hostname.fqdn,
                                 release=release.raw)
        else:
            return make_response(ERROR_KEY_3, hostname=hostname.fqdn)


    if __name__ == "__main__":
        from insights import run
        run(report, print_summary=True)

Install your rule repository into your virtualenv::

    (insights-core)[userone@hostone project_dir]$ cd myrule
    (insights-core)[userone@hostone project_dir/myrule]$ pip install -e .
    
Now you can use Insights to evaluate your rule by running your rule script::
    
    (insights-core)[userone@hostone project_dir/myrule]$ python MyRules/hostname_rel.py
    
Depending upon the computer you are using you will see several lines of
output ending with a your rule results that should look something like this::
    
    rule instances:
    '__main__.report:'
    {'error_key': 'RELEASE_IS_RHEL',
     'hostname': 'myhost.mydomain.com',
     'release': '7.4',
     'type': 'rule'}
     
By default Insights will collect information from your computer for evaluation
of your rules.  For a more detailed description of how to develop your own
rules see the Tutorial section :ref:`tutorial-rule-development`.

*****************
Contributor Setup
*****************

If you wish to contribute to the insights-core project you'll need to create a fork in GitHub.

1. Clone your fork::

    [userone@hostone project_dir]$ git clone <EMAIL>:your-user/insights-core.git

2. Reference the original project as "upstream"::

    [userone@hostone project_dir]$ cd insights-core
    [userone@hostone project_dir/insights-core]$ git remote add upstream <EMAIL>:RedHatInsights/insights-core.git

At this point, you would synchronize your fork with the upstream project
using the following commands::

    [userone@hostone project_dir/insights-core]$ git pull upstream master
    [userone@hostone project_dir/insights-core]$ git push origin master


After setup
===========

You can validate the setup by running the unit tests::
    
    [userone@hostone project_dir/insights-core]$ py.test

To generate docs::
    
    [userone@hostone project_dir/insights-core]$ cd docs/
    [userone@hostone project_dir/insights-core/docs]$ make html

And they can be found under `docs/_build/html`.

You will need to initialize the project per the
`README.rst <https://github.com/RedHatInsights/insights-core/blob/master/README.rst>`_
file.  For more detailed information about writing parsers and combiners see the
tutorial sections :ref:`tutorial-parser-development` and
:ref:`tutorial-combiner-development`.

***********************
Contributor Submissions
***********************

Contributors should submit changes to the code via GitHub "Pull
Requests."  One would normally start a new contribution with a branch
from the current master branch of the upstream project.
{'fraction_non_alphanumeric': 0.10868880843695891, 'fraction_numerical': 0.0028333070990083425, 'mean_word_length': 3.75739423436915, 'pattern_counts': {'":': 4, '<': 12, '<?xml version=': 0, '>': 12, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 1, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4131066', 'n_tokens_mistral': 3608, 'n_tokens_neox': 3496, 'n_words': 1260}