nbs/tutorials/contribution.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Contribute\n",
    "\n",
    "> How to contribute to `ReLax` "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Using JAX backend.\n"
     ]
    }
   ],
   "source": [
    "#| hide\n",
    "from __future__ import annotations\n",
    "from relax.import_essentials import *\n",
    "from nbdev.showdoc import show_doc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This library uses [nbdev](https://nbdev.fast.ai) for development. \n",
    "We love great flexibility offered by jupyter notebook, \n",
    "and [nbdev](https://nbdev.fast.ai) in addressing limitations of using Notebook in developing large-scale projects \n",
    "(e.g., sync between notebooks and python modules, documentations).\n",
    "\n",
    "Here, we only cover basis of our development procedure.\n",
    "For an in-depth use of [nbdev](https://nbdev.fast.ai), please refer to the [nbdev tutorial](https://nbdev.fast.ai/tutorials/).\n",
    "Following links are particularly useful:\n",
    "\n",
    "* [A step-by-step tutorial on using nbdev](https://nbdev.fast.ai/tutorials/tutorial.html)\n",
    "* [How to write code in Jupyter Notebook](https://nbdev.fast.ai/tutorials/best_practices.html)\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Set up the working environment\n",
    "\n",
    "\n",
    "Refer to [installation guidance](install.ipynb) for installing ReLax. \n",
    "For running `ReLax` in CPU, you should\n",
    "\n",
    "```bash\n",
    "pip install \"jax-relax[dev]\"\n",
    "```\n",
    "\n",
    "Next, install [Quarto](https://quarto.org/docs/get-started/) for the documentation system.\n",
    "See [nbdev docs](https://nbdev.fast.ai/tutorials/tutorial.html#install-quarto) for more details.\n",
    "\n",
    "\n",
    "```bash\n",
    "nbdev_install_quarto\n",
    "```\n",
    "\n",
    "\n",
    "\n",
    "Next, install [hooks](https://nbdev.fast.ai/tutorials/tutorial.html#install-hooks-for-git-friendly-notebooks) \n",
    "for cleaning Jupyter Notebooks.\n",
    "\n",
    "```\n",
    "nbdev_install_hooks\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Write Code in Jupyter Notebook\n",
    "\n",
    "Note that nbdev provides a [best practice guidline](https://nbdev.fast.ai/tutorials/best_practices.html) \n",
    "to writing code in Jupyter Notebooks. \n",
    "Here, we present some of the most important steps.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Export Cell to Python Module \n",
    "\n",
    "`#| export` marks code cells (in Notebook; `.ipynb`) to be exported to Python Module (`.py`).\n",
    "By default, this cell will be exported to the file defined in `#| default_exp file_name`\n",
    "(usually presented upfront).\n",
    "\n",
    "\n",
    "For example, the below function will be exported to the Python module.\n",
    "\n",
    "```python\n",
    "#| export\n",
    "def func(args):\n",
    "    ...\n",
    "```\n",
    "\n",
    "We can also specify files to be exported.\n",
    "\n",
    "```python\n",
    "#| export file_name.py\n",
    "def func(args):\n",
    "    ...\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For private functions/objects, we can use `#| exporti`. \n",
    "In this way, the code will still be exported to the file, but not included in `__all__`.\n",
    "\n",
    "\n",
    "More about [directives](https://nbdev.fast.ai/explanations/directives.html).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Two-way Sync between Notebooks (`.ipynb`) and Python Code (`.py`)\n",
    "\n",
    "To update code written in Jupyter Notebook to Python Module (i.e., `.ipynb` -> `.py`)\n",
    "\n",
    "```bash\n",
    "nbdev_export\n",
    "```\n",
    "\n",
    "To sync code updated in Python Module back to Jupyter Notebook (i.e., `.py` -> `.ipynb`)\n",
    "\n",
    "```bash\n",
    "nbdev_update\n",
    "```\n",
    "\n",
    ":::{.callout-warning}\n",
    "If you write a new function/object in `.py`, `nbdev_update` will not include this function in `__all__`.\n",
    "The best practice is to write functions/objects in Jupyter Notebook, and debug in Python Module (via IDE).\n",
    ":::\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Code Style\n",
    "\n",
    "`ReLax` follows the [black](https://black.readthedocs.io/en/stable/) code style.\n",
    "See [black's code style document](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Write Test Cases in Jupyter Notebook\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is desirable to write some unit tests for each function and object.\n",
    "[nbdev](https://nbdev.fast.ai) recommends to write test cases after implementing a feature.\n",
    "A normal cell is considered for testing.\n",
    "\n",
    "For example, let's consider a function which adds up all the inputs: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add_numbers(*args):\n",
    "    return sum(args)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To test this function, we write unit tests via `assert`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# check correctness\n",
    "assert add_numbers(1, 2, 3) == 6\n",
    "# check types\n",
    "assert type(add_numbers(1, 2, 3)) == int\n",
    "assert type(add_numbers(1., 2, 3)) == float"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::{.callout-note}\n",
    "Note that all the test cases should be quickly run.\n",
    "If a cell takes a long time to run (e.g., model training),\n",
    "mark the cell as `#| eval: false` to skip this cell.\n",
    ":::\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Write Documentations in Jupyter Notebook\n",
    "\n",
    "#### Doc string\n",
    "\n",
    "To write documentations in [nbdev](https://nbdev.fast.ai),\n",
    "it is recommended to \n",
    "\n",
    "1. use simple type annotations\n",
    "2. describe each arguments with short comments\n",
    "3. provide code examples and explanations in separate cells\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::{.callout-tip}\n",
    "Union typing is introduced after Python 3.10. \n",
    "For Python 3.7 - 3.9 users, you should \n",
    "\n",
    "```python\n",
    "from __future__ import annotations\n",
    "```\n",
    ":::"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def validate_configs(\n",
    "    configs: dict|BaseParser, # A configuration of the model/data.\n",
    "    config_cls: BaseParser # The desired configuration class.\n",
    ") -> BaseParser:\n",
    "    \"\"\"return a valid configuration object.\"\"\"\n",
    "    ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "nbdev will automatically render the documentation:\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "::: {.pt-3 .pb-1 .px-3 .mt-2 .mb-4 .border .rounded .shadow-sm}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 class=\"doc-title\" id=\"validate_configs\"><b>validate_configs</b></h4>::: {.doc-sig}\n",
       "\n",
       " <b>validate_configs</b> <em>(configs, config_cls)</em>\n",
       "\n",
       ":::\n",
       "\n",
       "return a valid configuration object.\n",
       "\n",
       "::: {#docs}\n",
       "\n",
       "**Parameters:**\n",
       "\n",
       "\n",
       "\n",
       "\n",
       "* <b>configs</b> (`dict | BaseParser`) -- A configuration of the model/data.\n",
       "* <b>config_cls</b> (`BaseParser`) -- The desired configuration class.\n",
       "\n",
       "\n",
       ":::\n",
       "\n",
       "\n",
       "::: {#docs}\n",
       "\n",
       "\n",
       "\n",
       "\n",
       "**Returns:**\n",
       "\n",
       "&ensp;&ensp;&ensp;&ensp;(`BaseParser`)\n",
       "\n",
       "\n",
       ":::"
      ],
      "text/plain": [
       "<relax.docs.CustomizedMarkdownRenderer>"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#| eval: false\n",
    "show_doc(validate_configs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we elaborate the use of this function with more descriptions and code examples."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| hide\n",
    "from relax.utils import validate_configs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "::: {.pt-3 .pb-1 .px-3 .mt-2 .mb-4 .border .rounded .shadow-sm}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We define a configuration object (which inherent `BaseParser`) \n",
    "to manage training/model/data configurations.\n",
    "`validate_configs` ensures to return the designated configuration object.\n",
    "\n",
    "For example, we define a configuration object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class LearningConfigs(BaseParser):\n",
    "    lr: float"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A configuration can be `LearningConfigs`, or the raw data in dictionary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "configs = dict(lr=0.01)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`validate_configs` will return a designated configuration object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "LearningConfigs(lr=0.01)"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "validate_configs(configs, LearningConfigs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### Callout\n",
    "\n",
    "We can also use [callout](https://quarto.org/docs/authoring/callouts.html) for clear documentations.\n",
    "\n",
    "```markdown\n",
    ":::{.callout-note}\n",
    "Note that there are five types of callouts, including:\n",
    "`note`, `warning`, `important`, `tip`, and `caution`.\n",
    ":::\n",
    "```\n",
    "\n",
    "which renders:\n",
    "\n",
    ":::{.callout-note}\n",
    "Note that there are five types of callouts, including:\n",
    "`note`, `warning`, `important`, `tip`, and `caution`.\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Preparing a Code Commit\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Preview the documentation system\n",
    "\n",
    "```bash\n",
    "nbdev_preview\n",
    "```\n",
    "\n",
    "If everything is in your satisfaction, prepare code before commit to GitHub\n",
    "\n",
    "```bash\n",
    "nbdev_prepare\n",
    "```\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "- Install all required packages based on [installation guidance](install.ipynb)\n",
    "- Install the git hook `nbdev_install_hooks`\n",
    "- Write code in Jupyter Notebooks; add approprate directives, e.g., `#| export`\n",
    "- Write tests after the code in the Notebooks; test the code via `nbdev_test`\n",
    "- Write documents directly in the Notebooks; preview the docs `nbdev_preview`\n",
    "- Prepare changes with `nbdev_prepare`\n",
    "- Create [pull requests](https:/BirkhoffG/ReLax/pulls) and push changes to GitHub"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "python3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}