Update docs (#17)

* update index.rst * update index.rst * update plot image in README.rst * update plot image in README.rst * update docs * update docs usage.rst * update docs * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * check automodule * update README.rst * update README.rst * update README.rst * update README.rst * update README.rst * update README.rst
kyosek · Jul 24, 2023 · 5cec6f0 · 5cec6f0
1 parent eed3487
commit 5cec6f0
Show file tree

Hide file tree

Showing 15 changed files with 133 additions and 248 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -5,6 +5,11 @@
 # Required
 version: 2
 
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
@@ -16,7 +21,7 @@ formats: all
 # to build the documentation automatically.
 python:
   install:
-    - requirements: requirements.txt
+    - requirements: docs/requirements.txt
 
 submodules:
   include: all

diff --git a/README.rst b/README.rst
@@ -1,4 +1,4 @@
-FOCUS: Flexible Optimizable Counterfactual Explanations for Tree Ensembles
+Focus-cfe
 ==========================================================================
 
 **Deployment & Documentation & Stats & License**
@@ -34,51 +34,82 @@ FOCUS: Flexible Optimizable Counterfactual Explanations for Tree Ensembles
    :target: https://github.com/kyosek/focus/blob/master/LICENSE
    :alt: License
 
------
+---------
+
+Focus-cfe generates optimal distance counterfactual explanations of the original data for the instances in tree‐based machine learning models.
 
-This library is an implementation of `FOCUS: Flexible Optimizable Counterfactual Explanations for Tree Ensembles <https://arxiv.org/abs/1911.12199>`_.
+This package is an implementation of `FOCUS: Flexible Optimizable Counterfactual Explanations for Tree Ensembles (Lucic, et at. 2022) <https://arxiv.org/abs/1911.12199>`_.
 
-FOCUS generates optimal distance counterfactual explanations to the original data for all the instances in tree‐based machine learning models.
+Installation
+------------
+
+It is recommended to use **pip** or **conda** for installation. Please make sure
+**the latest version** is installed:
+
+.. code-block:: bash
 
+   pip install focus-cfe            # normal install
+   pip install --upgrade focus-cfe  # or update if needed
+
+.. code-block:: bash
+
+   conda install -c conda-forge focus-cfe
+
+Requirements
+------------
+
+- Python 3.6+
+- numpy>=1.19.1
+- tensorflow>=2.0.0
+- scikit-learn>=1.0.2
+
+Usage
+-----
 **FOCUS counterfactual explanation generation with 3 Lines of Code**\ :
 
 .. code-block:: python
 
     from focus import Focus
     # Initialize Focus instance with default values
     focus = Focus()
+
     # Generate counterfactual explanations for given tree model and features
     pertubed = focus.generate(tree_model, X)
 
 
-**Examples**\:
+Examples
+--------
 
-- More comprehensive example can be found in the `examples folder <https://github.com/kyosek/focus/blob/master/examples/focus_example.py>`_.
-- Another example in a kaggle notebook can be found `here <https://www.kaggle.com/code/kyosukemorita/focus-cfe-example>`_.
-- Below demonstrates the comparison of before and after FOCUS was applied to feature set from the above example.
+- Comprehensive examples can be found in the `examples folder <https://github.com/kyosek/focus/blob/master/examples/focus_example.py>`_.
+- Kaggle notebook example can be found `here <https://www.kaggle.com/code/kyosukemorita/focus-cfe-example>`_.
+- Below is demonstrated a comparison of before and after Focus-cfe is applied to feature set from the example given above.
 
-.. image:: docs/plot.png
-    :width: 200px
-    :height: 100px
-    :scale: 50 %
+.. image:: https://raw.githubusercontent.com/kyosek/focus/master/docs/plot.png
+    :width: 800px
+    :height: 400px
+    :scale: 100 %
     :alt: Before and After FOCUS was applied to the features from above example.
 
-**Limitations**\:
+Limitations
+-----------
 
-- Currently, FOCUS can only be applied to scikit-learn `DecisionTreeClassifier`, `RandomForestClassifier` and `AdaBoostClassifier`.
+- Currently, Focus-cfe can only be applied to scikit-learn ``DecisionTreeClassifier``, ``RandomForestClassifier`` and ``AdaBoostClassifier``.
 - While categorical features may be included in the feature set, it is important to note that the interpretation of changes in categorical features, such as transitioning from age 40 to 20, may not provide meaningful insights.
-- The input features should be scaled to the range of 0 and 1 before applying FOCUS. Therefore, it is necessary to transform the features prior to using FOCUS. However, this scaling process may introduce some additional complexity when interpreting the features after applying FOCUS.
+- The input features should be scaled to the range of 0 and 1 before applying Focus-cfe. Therefore, it is necessary to transform the features prior to using Focus-cfe. However, this scaling process may introduce some additional complexity when interpreting the features after applying Focus-cfe.
 
-^^^^^^^^^^^^
+Documentation
+-------------
 
-It is recommended to use **pip** or **conda** for installation. Please make sure
-**the latest version** is installed:
+The documentation can be found `here <https://focus-cfe.readthedocs.io/en/latest/>`_.
 
-.. code-block:: bash
+Contributing
+------------
 
-   pip install focus-cfe            # normal install
-   pip install --upgrade focus-cfe  # or update if needed
+If you would like to contribute to the project, please refer to;
 
-.. code-block:: bash
+- `ISSUE_TEMPLATE <https://github.com/kyosek/focus/tree/master/.github/ISSUE_TEMPLATE>`_ for raising an issue
+- `PULL_REQUEST_TEMPLATE.md <https://github.com/kyosek/focus/blob/master/.github/PULL_REQUEST_TEMPLATE.md>`_ for raising a PR
 
-   conda install -c conda-forge focus-cfe
+License
+-------
+This package is using the `Apache License 2.0 <https://github.com/kyosek/focus/blob/master/LICENSE>`_ license.
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,21 @@
+=============
+API Reference
+=============
+
+Focus
+-----
+
+.. autoclass:: focus.core.Focus
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
+Utils
+-----
+
+.. automodule:: focus.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
diff --git a/docs/conf.py b/docs/conf.py
@@ -13,7 +13,7 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath("."))
+sys.path.insert(0, os.path.abspath(".."))
 
 
 # -- Project information -----------------------------------------------------
@@ -36,7 +36,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "tests"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -45,8 +45,3 @@
 # a list of builtin themes.
 #
 html_theme = "sphinx_rtd_theme"
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
diff --git a/docs/core.rst b/docs/core.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,38 +1,17 @@
-.. focus-cfe documentation master file, created by
-   sphinx-quickstart on Mon Jul 10 23:27:26 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-.. module:: focus-cfe
+.. include:: ../README.rst
 
-***********************
-focus-cfe documentation
-***********************
-
-**Date**: |today| **Version**: |version|
-
-**GitHub Repository**: |
-`focus <https://github.com/kyosek/focus>`__ |
+**Links**: |
+`GitHub repository <https://github.com/kyosek/focus>`__ |
+`PyPI <https://pypi.org/project/focus-cfe/>`__ |
 
 =====================================
 
-.. automodule:: focus-cfe
-   :members:
-
---------------------------
-
-**Sub-Modules:**
+Contents
+--------
 
 .. toctree::
-   :maxdepth: 1
-
-   README
-   core
-   utils
-
-
-Indices and tables
-==================
+   :maxdepth: 2
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   Home <self>
+   usage
+   api
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,8 @@
+# Defining the exact version will make sure things don't break
+sphinx==5.3.0
+sphinx_rtd_theme==1.1.1
+readthedocs-sphinx-search==0.1.1
+numpy>=1.19.1
+tensorflow>=2.0.0
+
+scikit-learn>=1.0.2
diff --git a/docs/source/README.rst b/docs/source/README.rst
diff --git a/docs/source/api/focus-cfe.rst b/docs/source/api/focus-cfe.rst
diff --git a/docs/source/focus.rst b/docs/source/focus.rst