Fix API Docs Configurations and Add Pages (#115)

Fix API docs with myst-parser and sphinx configs + more cleanups ...

Co-authored-by: Amirhessam Tahmassebi <[email protected]>

CHANGELOG.md

@@ -1,125 +1,123 @@
-# Changelog
-All notable changes to this project will be documented in this file.
-This project adheres to [Semantic Versioning](http://semver.org/).
+📣 🥁 Changelog & Releases
+=========================
 
-## Unreleased Version X.X.X - XXXX-XX-XX
+- We follow [Semantic Versioning](http://semver.org/) to document any notable changes.
+- Please checkout [SlickML Official Releases](https:/slickml/slick-ml/releases) for more details.
 
-### Fixed
+---
 
-### Updated
+## 📍 Unreleased Version X.X.X - XXXX-XX-XX
 
-### Added
+### 🛠 Fixed
 
-## Version 0.2.0-beta - 2022-05-29
+### 🔥 Added
 
-### Fixed
+---
+
+## 📍 Version 0.2.0-beta - 2022-05-29
+
+### 🛠 Fixed
 - [#78](https:/slickml/slick-ml/pull/78) `build` badge using GitHub actions and removed the `travis-ci` badge and dependencies.
-- 
-### Updated
 - [#77](https:/slickml/slick-ml/pull/77) updated `.flake8`, `.gitingore` entries, `ISSUE_TEMPLATES`, `README.md`, `CONTRIBUTING.md`, `assets/`, `examples/` formats, and `src/` style, `ci.yml` workflow.
 
-### Added
+### 🔥 Added
 - [#77](https:/slickml/slick-ml/pull/77) added poetry essentials and essentials based on [#72](https:/slickml/slick-ml/pull/72) and removed all `setup.py` essentials.
 - [#77](https:/slickml/slick-ml/pull/77) added `tox`, `mypy`, `pytest-cov`.
 - [#77](https:/slickml/slick-ml/pull/77) added `sphinx-auto-api-doc` based on [#32](https:/slickml/slick-ml/pull/32). 
 
+---
 
-## Version 0.1.5 - 2021-09-06
+## 📍 Version 0.1.5 - 2021-09-06
 
-### Updated
+### 🛠 Fixed
 - [#74](https:/slickml/slick-ml/pull/74) updated `requirements.txt` to the latest versions.
 - [#71](https:/slickml/slick-ml/pull/71) updated optimization examples.
 
-### Added
+### 🔥 Added
 - [#71](https:/slickml/slick-ml/pull/71) added `XGBoostRegressorBayesianOpt` and `XGBoostRegressorHyperOpt` classes in optimization. 
 
-## Version 0.1.4 - 2021-05-31
+---
 
-### Fixed
+## 📍 Version 0.1.4 - 2021-05-31
+
+### 🛠 Fixed
 - [#70](https:/slickml/slick-ml/pull/70) fixed bugs in `plot_xgb_cv_results`. 
 - [#70](https:/slickml/slick-ml/pull/70) fixed bugs in `plot_regression_metrics`. 
-
-### Updated
 - [#70](https:/slickml/slick-ml/pull/70) updated metrics initialization in `XGBoostClassifier` and `XGBoostCVClassifier`.
 - [#70](https:/slickml/slick-ml/pull/70) updated notebook examples to go over each class separetely.
 
-### Added
+### 🔥 Added
 - [#70](https:/slickml/slick-ml/pull/70) added `XGBoostRegressor` and `XGBoostCVRegressor` classes.
 - [#70](https:/slickml/slick-ml/pull/70) added `NeurIPS 2021` submission pdf.
 
+---
 
-## Version 0.1.3 - 2021-05-15
+## 📍 Version 0.1.3 - 2021-05-15
 
-### Fixed
+### 🛠 Fixed
 - [#66](https:/slickml/slick-ml/pull/66) fixed bugs in feature selection algorithm. 
 - [#67](https:/slickml/slick-ml/pull/67) fixed bugs in metrics. 
-
-### Updated
 - [#66](https:/slickml/slick-ml/pull/66) updated the order of the functions inside each class.
 - [#68](https:/slickml/slick-ml/pull/68) updated `save_path` in plotting functions.
 - [#68](https:/slickml/slick-ml/pull/68) updated `bibtex` citations to software.
 
-### Added
+### 🔥 Added
 - [#68](https:/slickml/slick-ml/pull/68) added directories for `JOSS` and `NeurIPS` papers.
 
+---
 
-## Version 0.1.2 - 2021-04-17
+## 📍 Version 0.1.2 - 2021-04-17
 
-### Fixed
+### 🛠 Fixed
 - [#63](https:/slickml/slick-ml/pull/63) fixed bugs in RegressionMetrics plotting. Now, the text label positions are dynamic and invariat of the data. Additionally, fixed the bug in coef. shapes in `GLMNet` classes. 
-
-### Updated
 - [#61](https:/slickml/slick-ml/pull/61) updated `metrics.py` attributes API to end with under-score
 - [#63](https:/slickml/slick-ml/pull/63) updated all docstrings based on Scikit-Learn API
 - [#64](https:/slickml/slick-ml/pull/64) updated `setup.py` with dynamic version and install requirements
 
-### Added
+### 🔥 Added
 - [#60](https:/slickml/slick-ml/pull/60) added `CHANGELOG.md`
 - [#63](https:/slickml/slick-ml/pull/63) added `GLMNetCVRegressor` class
 
-## Version 0.1.1 - 2021-03-18
+---
+
+## 📍 Version 0.1.1 - 2021-03-18
 
-### Fixed
+### 🛠 Fixed
 - [#54](https:/slickml/slick-ml/pull/54) fixed bug in XGBoostClassifer. dtest has `y_test` as required parameter while it should be optional, since you wont have the `y_true` in production.
 - [#56](https:/slickml/slick-ml/pull/56) fixed bugs in plotting
-
-### Updated
 - [#57](https:/slickml/slick-ml/pull/57) updated `requirements.txt`
 - [#59](https:/slickml/slick-ml/pull/59) updated docstrings
 
-### Added
+### 🔥 Added
 - [#44](https:/slickml/slick-ml/pull/44) added XGBoostClassifierHyperOpt
 - [#57](https:/slickml/slick-ml/pull/57) added GLMNetCVClassifier class, plotting, and examples, `CODE_OF_CONDUCT.md`
 
-## Version 0.0.8 - 2021-02-17
+---
 
-### Fixed
-- [#47](https:/slickml/slick-ml/pull/47) fixed bugs in HyperOpt `__init__`
+## 📍 Version 0.0.8 - 2021-02-17
 
-### Updated
+### 🛠 Fixed
+- [#47](https:/slickml/slick-ml/pull/47) fixed bugs in HyperOpt `__init__`
 - [#52](https:/slickml/slick-ml/pull/52) updated xgboost version to 1.0.0 to remove the conflict with shap version
 
-### Added
+### 🔥 Added
 - [#44](https:/slickml/slick-ml/pull/44) added XGBoostClassifierHyperOpt
 - [#49](https:/slickml/slick-ml/pull/49) added Google Colab links to notebooks
 - [#51](https:/slickml/slick-ml/pull/51) added regression metrics
 - [#52](https:/slickml/slick-ml/pull/52) added SHAP waterfall plot
 
+---
 
-## Version 0.0.7 - 2020-09-27
+## 📍 Version 0.0.7 - 2020-09-27
 
-### API Changes
+### 🛠 Fixed
 - [#28](https:/slickml/slick-ml/pull/28) updated feature selection method from run to fit and removed X, y from init and added to fit to be similar to sklearn API.
 - [#17](https:/slickml/slick-ml/pull/17) updated plotting to Matplotlib object oriented API
-
-## Fixed
 - [#34](https:/slickml/slick-ml/pull/34) fixed formatting and import bugs in source code
 - [#38](https:/slickml/slick-ml/pull/38) fixed typos in README and bug in `df_to_csr` function
-
-### Updated
 - [#41](https:/slickml/slick-ml/pull/41) updated requirements for bayesian optimization, design pattern, classification examples
 
-### Added
+### 🔥 Added
 - [#4](https:/slickml/slick-ml/pull/4) added `metrics.py`
 - [#6](https:/slickml/slick-ml/pull/6) added logo design
 - [#9](https:/slickml/slick-ml/pull/9) added plots for metrics and `utilities.py`
@@ -132,7 +130,9 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - [#38](https:/slickml/slick-ml/pull/38) added unit tests for classification
 - [#43](https:/slickml/slick-ml/pull/43) added BayesianOpt class
 
+---
+
+## 📍 Version 0.0.1 - 2020-08-31
 
-## Version 0.0.1 - 2020-08-31
-### Added
+### 🔥 Added
 - [#2](https:/slickml/slick-ml/pull/2) initial ideas

CONTRIBUTING.md

@@ -150,9 +150,10 @@ Please note that before starting any major work, open an issue describing what y
  poe sphinx
  ```
 - The generated API documentation file can be found at `docs/_build/index.html`.
+- You can also add a new page in `.rst` or `md` formats under `docs/page`.
+- All `sphinx` configurations that we are using are available in `docs/conf.py`.
 
-
-### 🔥 Pull Requests
+## 🔥 Pull Requests
 - We currently have `bug-report` and `feature-request` as [*issue-templates*](https:/slickml/slick-ml/issues). As laid out above, please make sure to open-up an issue before start working on a major work and get the core team feedback.
 - Try to fix one bug or add one new feature per PR. This would minimize the amount of code changes and it is easier for code-review. Hefty PRs usually do not get merged so fast while it could have been if the work was splitted into multiple PRs clearly laid out in an issue before hand. Therefore, the code reviewer would not be surprised by the work.
 - We recommend to follow [*Fork and Pull Request Workflow*](https:/susam/gitpr).

README.md

@@ -10,13 +10,25 @@
 
 
 <p align="center">
-<a href="https://www.docs.slickml.com/">
- <img src="https://raw.githubusercontent.com/slickml/slick-ml/master/assets/designs/logo_clear.png" width="250"></img></a>
+ <a href="https://www.docs.slickml.com/">
+ <img src="https://raw.githubusercontent.com/slickml/slick-ml/master/assets/designs/logo_clear.png" width="250"></img>
+ </a>
 </p>
 
-<h1 align="center">
- SlickML🧞: Slick Machine Learning in Python
-</h1>
+<div align="center">
+<h1 align="center">SlickML🧞: Slick Machine Learning in Python</h1>
+ <p align="center">
+ <a href="https:/slickml/slick-ml/releases"> Explore Releases</a>
+ 🟣 
+ <a href="https:/slickml/slick-ml/blob/master/CONTRIBUTING.md"> Be a Contributor</a>
+ 🟣 
+ <a href="https://www.docs.slickml.com"> Explore API Docs</a>
+ 🟣 
+ <a href="https://www.slickml.com/slack-invite"> Join our Slack</a>
+ 🟣 
+ <a href="https://twitter.com/slickml"> Tweet Us</a> 
+ </p>
+</div>
 
 
 **SlickML** is an open-source machine learning library written in Python aimed

docs/conf.py

@@ -28,12 +28,16 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
+# Reference: https://www.sphinx-doc.org/en/master/usage/extensions/index.html
 extensions = [
  "sphinx.ext.autodoc",
  "sphinx.ext.intersphinx",
  "sphinx.ext.napoleon",
  "sphinx.ext.doctest",
  "autoapi.extension",
+ "sphinx.ext.viewcode",
+ "sphinx.ext.todo",
+ "myst_parser",
 ]
 
 # Auto-API directories
@@ -42,7 +46,9 @@
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+templates_path = [
+ "_templates",
+]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -57,39 +63,53 @@
  ".ipynb_checkpoints",
 ]
 
-# numpydoc configuration
-numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings
-numpydoc_class_members_toctree = False
-
 # The name of the Pygments (syntax highlighting) style to use.
 # pygments_style = "sphinx"
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
+numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings
+numpydoc_class_members_toctree = False
 
 # -- Options for HTML output -------------------------------------------------
 # The theme to use for HTML and HTML Help pages. See the documentation for
 # a list of builtin themes.
-#
+# References:
+# - https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html
+# - https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes
+# - https:/BusKill/buskill-app/blob/b604e23535bb27f1ecb0c3311a8c55bf34f88ef8/docs/conf.py#L99-L106
+
 html_theme = "sphinx_rtd_theme"
 html_logo = "../assets/designs/logo_clear.png"
 html_favicon = "../assets/designs/logo_clear.png"
 html_show_copyright = True
 html_show_search_summary = True
 html_show_sphinx = True
 html_output_encoding = "utf-8"
+github_url = "https:/slickml/slick-ml"
 
 # 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"]
+html_static_path = [
+ "_static",
+]
+
+# Replace "view page source" with "edit on github" in Read The Docs theme
+# Reference: https:/readthedocs/sphinx_rtd_theme/issues/529
+html_context = {
+ "display_github": True,
+ "github_user": "slickml",
+ "github_repo": "slick-ml",
+ "github_version": "master/docs/",
+}
+
 
 # -- Options for Auto-API-Docs -------------------------------------------------
 # Reference: https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html
 autoapi_type = "python"
 autoapi_template_dir = ""
-autoapi_file_patterns = ["*.py", "*.pyi"]
+autoapi_file_patterns = [
+ "*.py",
+ "*.pyi",
+]
 autoapi_generate_api_docs = True
 autoapi_options = [
  "members",
@@ -100,11 +120,39 @@
  "special-members",
  "imported-members",
 ]
-autoapi_ignore = ["*migrations*"]
+autoapi_ignore = [
+ "*migrations*",
+]
 autoapi_add_toctree_entry = True
 autoapi_python_class_content = "class"
 autoapi_member_order = "alphabetical"
 autoapi_python_use_implicit_namespaces = False
 autoapi_prepare_jinja_env = None
 autoapi_keep_files = False
 suppress_warnings = []
+
+# -- Options for View-Code -------------------------------------------------
+viewcode_follow_imported_members = True
+
+
+# -- Options for Napoleon -------------------------------------------------
+# Reference: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = False
+napoleon_use_rtype = False
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True
+
+
+# -- Options for TODOs -------------------------------------------------
+# Reference: https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
+todo_include_todos = False