index.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# nbagile\n",
    "\n",
    "> Making `nbdev` more Agile-Friendly"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Install"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`pip install nbagile`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Goals:\n",
    "\n",
    "- [x] When exporting source code using `docments`, attach and format the docstring to Numpy format\n",
    "- [ ] Export tests and throw them into a pytest-compatible file format\n",
    "- [ ] Make documentation run on Sphynx\n",
    "- [ ] Tests are exported to a `tests` folder, source code to a source code folder, and Markdown/Sphynx documentation to a `docs` folder\n",
    "- [ ] Individual notebooks can then be recreated from these three items"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Current Capabilities\n",
    "\n",
    "\n",
    "### Using the CLI\n",
    "\n",
    "Replace `nbdev_` commands with `nbagile_` to use it's capabilities. \n",
    "**Currently Supported**:\n",
    "- `nbagile_build_lib`: Exports code and converts it to black-style + NumPy docstrings\n",
    "- `nbagile_diff_nbs`: A special version of `nbdev_diff_nbs` to support how nbagile works\n",
    "- `nbagile_build_docs`: Builds the docs using [nbverbose](https://muellerzr.github.io/nbverbose)\n",
    "\n",
    "### Exporting code from `docments` to NumPy\n",
    "\n",
    "[docments](https://fastcore.fast.ai/docments) is a very efficient way of documenting the parameters for your code, and is akin to how javscript is documented. We utilize comment-blocks and typing to describe how parameters are utilized. For example, we have the following:\n",
    "\n",
    "```python\n",
    "def addition(\n",
    "    a:int, # The first number to add\n",
    "    b:(int,float), # The second number to add\n",
    ") -> int: # The sum of a and b\n",
    "    \"Adds a and b\"\n",
    "    return a+b\n",
    "```\n",
    "\n",
    "But this is not the commonly accepted way of documenting our code, and as a whole looks quite ugly.\n",
    "\n",
    "`nbagile` supports building your [nbdev](https://nbdev.fast.ai) built libraries to instead automatically convert this code into a more NumPy-styled documentation string and definition, with the added bonus of it mimicing the Black format:\n",
    "\n",
    "```python\n",
    "def addition(a,b):\n",
    "    \"\"\"Adds a and b\n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    a : int\n",
    "      The first number to add\n",
    "    b : (int,float)\n",
    "      The second number to add\n",
    "      \n",
    "    Returns\n",
    "    ----------\n",
    "    int\n",
    "      The sum of a and b\n",
    "    \"\"\"\n",
    "    return a+b\n",
    "```\n",
    "\n",
    "This works for functions, classes, as well as functions wrapped around decorators.\n",
    "\n",
    "\n",
    "### Optional `__all__` for nbdev\n",
    "\n",
    "If you are not a fan of nbdev's `__all__` format in each file, there is an additional setting you can add to your `settings.ini`: `use_all`.\n",
    "\n",
    "If set to `False`, you won't get the `__all__` being generated in each python file"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}