unify docs base modules and creation closes #167 (#184)

* unify docs base modules and creation

* fix line too long

* unify and expand arbitrary discretisation docs

* fixed indentation in docstrings

* add link fix indentation

* expand doc discretisation with trees

* expand rest of discretisers

* expand and unify doc for encoders

* fix raises docstring format

* fix raises docstring format

* enhance doc layout, add navigation tabs

* expand docs for imputers

* expand docs for transformers

* expand docs for wrapper

* expand docs for outliers

* fix style error

* fix import and errors in boxcox yeojohsnon

* tweak conf further

* link API docs to github

* final edit to imputers

* final edits encoders and imputers

* final edits var transformers

* final edits discretisation

* final edits outliers

* final edit creation

* unify docstrings selectors

* updated changelog

* tidy docs

* final edits, ready to merge, waiting to see if can resolve warning issue

* fix tedious warning on fit, transform methods

* add missing attribute to recursive selector

Author: solegalli

docs/_static/css/feature-engine.css

@@ -0,0 +1,14 @@
+@import url("theme.css");
+
+.highlight a {
+    text-decoration: underline;
+}
+
+.wy-nav-content {
+    max-width: 1200px !important;
+}
+
+
+.wy-table-responsive {
+    overflow: visible !important;
+}

docs/_templates/breadcrumbs.html

@@ -0,0 +1,4 @@
+{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
+
+{% block breadcrumbs_aside %}
+{% endblock %}

docs/_templates/numpydoc_docstring.rst

@@ -0,0 +1,16 @@
+{{index}}
+{{summary}}
+{{extended_summary}}
+{{parameters}}
+{{returns}}
+{{yields}}
+{{other_parameters}}
+{{attributes}}
+{{raises}}
+{{warns}}
+{{warnings}}
+{{see_also}}
+{{notes}}
+{{references}}
+{{examples}}
+{{methods}}

docs/about.rst

@@ -0,0 +1,6 @@
+.. -*- mode: rst -*-
+
+About
+=====
+
+Coming Soon!

docs/blogs.rst

@@ -0,0 +1,30 @@
+Blogs and Videos
+================
+
+Articles and videos about Feature-engine and feature engineering and selection in general.
+
+Blogs
+-----
+
+- `Feature-engine: A new open-source Python package for feature engineering <https://www.trainindatablog.com/feature-engine-a-new-open-source-python-package-for-feature-engineering/>`_.
+- `Practical Code Implementations of Feature Engineering for Machine Learning with Python <https://www.trainindatablog.com/practical-code-implementations-of-feature-engineering-for-machine-learning-with-python/>`_.
+- `Streamlining Feature Engineering Pipelines with Feature-engine <https://towardsdatascience.com/streamlining-feature-engineering-pipelines-with-feature-engine-e781d551f470?gi=e0fa6e5c0c1a/>`_.
+- `Feature Engineering for Machine Learning: A comprehensive Overvoew <https://www.trainindatablog.com/feature-engineering-for-machine-learning-comprehensive-overview/>`_.
+- `Feature Selection for Machine Learning: A comprehensive Overview <https://www.trainindatablog.com/feature-selection-for-machine-learning-comprehensive-overview/>`_.
+
+
+Videos
+------
+
+- Coming soon!
+
+En Español
+----------
+
+- `Ingeniería de variables para machine learning <https://www.udemy.com/course/ingenieria-de-variables-para-machine-learning/?referralCode=CE398C784F17BD87482C>`_, Curso Online.
+- `Ingeniería de variables, MachinLenin <https://www.youtube.com/watch?v=NhCxOOoFXds>`_, charla con video online.
+- `Ingeniería de atributos para aprendizaje automático: una revisión completa <https://www.trainindatablog.com/ingenieria-de-variables-aprendizaje-de-maquinas/>`_, Artículo.
+- `Paquetes Python de código abierto para la ingeniería de atributos: Comparaciones y conclusiones <https://www.trainindatablog.com/paquetes-python-de-para-ingenieria-de-atributos/>`_, Artículo.
+- `Feature-engine: Un paquete Python de código abierto para la ingeniería de atributos <https://www.trainindatablog.com/feature-engine-un-paquete-python-de-codigo-abierto-para-la-ingenieria-de-atributos/>`_, Artículo.
+
+More resources will be added as they appear online!

docs/books.rst

@@ -0,0 +1,12 @@
+Books
+=====
+
+You can learn more about how to use Feature-engine and feature engineering in general
+in the following books:
+
+.. figure::  images/cookbook.png
+   :width: 200
+   :align: left
+   :target: https://www.packtpub.com/product/python-feature-engineering-cookbook/9781789806311
+
+   Python Feature Engineering Cookbook

docs/conf.py

@@ -13,63 +13,71 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-# 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
+import sphinx_rtd_theme
 
-sys.path.insert(0, os.path.abspath("."))
-sys.path.insert(0, os.path.abspath("../"))
+# 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.
+# sys.path.insert(0, os.path.abspath("."))
+# sys.path.insert(0, os.path.abspath("../"))
 sys.path.insert(1, os.path.dirname(os.path.abspath("../")) + os.sep + "feature_engine")
+sys.path.insert(0, os.path.abspath("sphinxext"))
+from github_link import make_linkcode_resolve
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#
 # needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx.ext.autodoc",
-    #    'sphinx.ext.doctest',
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.todo",
-    "sphinx.ext.coverage",
-    #   'sphinx.ext.mathjax',
-    #   'sphinx.ext.ifconfig',
-    "sphinx.ext.viewcode",
-    "sphinx.ext.githubpages",
-    #    'sphinx.ext.autosummary',
-    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",  # Core Sphinx library for auto html doc generation from docstrings
+    "sphinx.ext.autosummary",  # Create neat summary tables for modules/classes/methods etc
+    "sphinx.ext.intersphinx",  # Link to other project's documentation (see mapping below)
+    "sphinx_autodoc_typehints",  # Automatically document param types (less noise in class signature)
     "numpydoc",
+    "sphinx.ext.linkcode",
+    # "sphinx.ext.doctest",
+    # "sphinx.ext.todo",
+    # "sphinx.ext.coverage",
+    # "sphinx.ext.mathjax",
+    # "sphinx.ext.ifconfig",
+    # "sphinx-prompt",
 ]
 
+# this is needed for some reason...
+# see https://github.com/numpy/numpydoc/issues/69
 numpydoc_show_class_members = False
+numpydoc_attributes_as_param_list = False
 
-napoleon_google_docstring = False
-napoleon_use_param = True
-napoleon_use_ivar = False
+# autodoc_default_options = {
+# #     "members": True,
+# #     "inherited-members": False,
+# # }
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
+# generate autosummary even if no references
+autosummary_generate = True
+autosummary_imported_members = True
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-#
 # source_suffix = ['.rst', '.md']
 source_suffix = ".rst"
 
 # The master toctree document.
 master_doc = "index"
 
 # General information about the project.
-project = "feature-engine"
-copyright = "2018-2020, Soledad Galli"
-author = "Soledad Galli"
+project = "Feature-engine"
+copyright = "2018-2021, Feature-engine developers"
+author = "Feature-engine developers"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -78,7 +86,7 @@
 VERSION_PATH = "../feature_engine/VERSION"
 with open(VERSION_PATH, "r") as version_file:
     v = version_file.read().strip()
-#
+
 # The short X.Y version.
 version = v
 # The full version, including alpha/beta/rc tags.
@@ -94,7 +102,11 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = []
+exclude_patterns = ["_build", "_templates"]
+
+# The reST default role (single back ticks `dict`) cross links to any code
+# object (including Python, but others as well).
+default_role = "literal"
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
@@ -110,6 +122,9 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 
+# Custom style
+html_style = "css/feature-engine.css"
+
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
@@ -124,13 +139,38 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    "logo_only": True,
+    "style_nav_header_background": "#e09200",
+    "canonical_url": "https://feature-engine.readthedocs.io/en/latest/",
+}
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # 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 = []
-autoclass_content = "both"
+html_static_path = ["_static"]
+# autoclass_content = "both"
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = version
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = "images/Logo.png"
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = "images/favicon.png"
+
+# 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']
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 html_show_sphinx = True
@@ -168,11 +208,21 @@
         master_doc,
         "feature_engine.tex",
         "feature\\_engine Documentation",
-        "Soledad Galli",
+        "Feature-engine Developers",
         "manual",
     ),
 ]
 
+# intersphinx configuration
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/{.major}".format(sys.version_info), None),
+    "numpy": ("https://docs.scipy.org/doc/numpy/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
+    "matplotlib": ("https://matplotlib.org/", None),
+    "sklearn": ("http://scikit-learn.org/stable", None),
+}
+
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
@@ -220,3 +270,11 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"https://docs.python.org/": None}
+
+# The following is used by sphinx.ext.linkcode to provide links to github
+linkcode_resolve = make_linkcode_resolve(
+    "feature_engine",
+    "https://github.com/solegalli/feature_engine/"
+    "blob/master/"
+    "{package}/{path}#L{lineno}",
+)

docs/contributing/building_the_docs.rst docs/contribute/building_the_docs.rstdocs/contributing/building_the_docs.rst renamed to docs/contribute/building_the_docs.rst

@@ -9,9 +9,8 @@ A typical contributing workflow goes like this:
 
 1. **Find** a bug while using Feature-engine, **suggest** new functionality, or **pick
 up** an issue from our `repo <https://github.com/solegalli/feature_engine/issues/>`_.
-2. **Discuss** with us how you would like to get involved and your approach to resolve
-the issue.
 
+2. **Discuss** with us your approach to resolve the issue.
 3. Then, **fork** the repository into your GitHub account.
 4. **Clone** your fork into your local computer.
 5. **Code** the feature, the tests and update or add the documentation.