Installing H2O AutoDoc
======================

.. _autodoc-requirements-ref:

H2O AutoDoc Requirements
------------------------

   - Python 3.6, 3.7 or 3.8
   - H2O-3 3.24.0.1 or higher
   - A supported H2O model. Supported models include:

     - Deep Learning
     - Distributed Random Forest (including Extremely Randomized Forest)
     - Generalized Linear Model
     - Gradient Boosting Machine
     - Stacked Ensembles
     - XGBoost

H2O AutoDoc Setup & Installation
--------------------------------

1. Install the required dependencies for h2o_autodoc.

    * Pandoc

      **Pandoc Note:**

         * MacOS X users can use `HomeBrew <https://brew.sh>`__ to install Pandoc (example shown below).
         * For additional download instructions see the `Pandoc Download's page <https://pandoc.org/installing.html>`__

.. tabs::
   .. code-tab:: bash Mac OSX

    # example using HomeBrew
    brew install pandoc

   .. code-tab:: bash Linux

    # example for Ubuntu
    wget https://github.com/jgm/pandoc/releases/download/2.9.1.1/pandoc-2.9.1.1-1-amd64.deb
    dpkg -i pandoc*.deb


2. Download and install the H2O AutoDoc.

* Run the following to pip install latest H2O AutoDoc:

.. substitution-code-block:: bash

    pip install h2o_autodoc

* Alternatively, run the following to pip install a specific version of H2O AutoDoc:

.. substitution-code-block:: bash

    pip install h2o_autodoc==|SUBST_AUTODOC_VERSION|

3. Create your first H2O AutoDoc - follow mini-tutorials in :ref:`autodoc-configuration-ref` section.

.. _autodoc-license-key-example-ref:

H2O AutoDoc License Key
-----------------------

The H2O AutoDoc Python package requires a license key. The license key can be specified through several options:

* Through a Config class parameters:

    * license_file: the file system location for the license file
    * license_text: the license text

* Through an Environment variable:

    * 'AUTODOC_LICENSE_FILE': the location of file containing the license key
    * 'AUTODOC_LICENSE_KEY': the license key

* Through License file in standard location:

    * /license/license.sig: the file containing the license key
    * ~/.h2o_autodoc/license.sig: the file containing the license key on user home

Setting License Key Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following example shows how to set your license key as the `license_text` string parameter in the Config class.

.. code-block:: python

    # H2O AutoDoc package imports
    from h2o_autodoc import Config
    from h2o_autodoc import render_autodoc

    # specify the full path to your H2O AutoDoc Report
    output_file_path = 'full/path/to/your/autodoc/report_H2O3.docx'
    config = Config(output_path=output_file_path, license_text="your license key here")

    # generate an H2O AutDoc report for your model and train dataset
    render_autodoc(h2o=h2o, config=config, model=model, train=train)