{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notebook Style Guide\n",
    "\n",
    "Keywords: style guide, notebook format"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Maintaining a collection of Jupyter notebooks requires attention several important details, among them are the structure and style of the individual notebooks. Maintaining a consistent notebook structure and style enables the use of tools to automate management of the overall collection. The purpose of this notebook is document the standards adopted for this particular collection."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Notebook naming and ancillary/generated files\n",
    "\n",
    "All notebooks in a repository should reside in a top-level directory named `notebooks`. The filenames begin with a prefix indicating their position in book-like organization. The first two digits indicate a chapter number with 00 reserved for front matter. Replacing the digits with a character indicates an appendix. Following a separating '.', a second pair of digits indicates a section with the front matter, chapter, or appendix. A hyphen separates the prefix from the rest of the filename. The standard `.ipynb` Jupyter notebook suffix is required.\n",
    "\n",
    "    my-repository-title/\n",
    "    |-- notebooks/\n",
    "        |--data/\n",
    "        |--figures/\n",
    "        |--00.00-Front-Matter.ipynb\n",
    "        |--00.01-Preface.ipynb\n",
    "        |--00.02-Acknowledgments.ipynb\n",
    "        |--01.00-Getting-Started.ipynb\n",
    "        |--01.01-First-Section.ipynb\n",
    "        |--02.00-Second-Chapter.ipynb\n",
    "        |--A.00-Style-Guid\n",
    "        \n",
    "This style guide assumes the use of software tools to manage the collection of notebooks. The software tools will perform the following tasks:\n",
    "\n",
    "* Generate a `Readme.md` file to be written to the top-level directory.\n",
    "* Generate a table of contents written to `toc.md` and `toc.ipynb` in the notebooks directory.\n",
    "* Insert and update a common header for all notebooks\n",
    "* Insert and update a navigation bar located in the second and terminal cell of each notebook.\n",
    "* A listing of all links and figures found in the notebooks.\n",
    "* A listing of stylistic `lint` encountered during the processing of the notebooks."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Notebook title and headers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Title\n",
    "Each notebook begins with a markdown level 1 header containing the title of the corresponding chapter or section. This should be capitalized following the Chicago Manual of Style. The hashtag `#` appears as the first line in the cell, and there is one and only one level 1 header per notebook. The title cell may include a brief summary of the notebook contents."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Subheadings\n",
    "\n",
    "A notebook will typically consist of multiple sections.  The sections are organized hierarchically as markdown headings. Following the document title, the highest level heading begins as markdown level 2 (i.e., `##`). The hierarchy is strict meaning that the next level in the hierarchy, `###`, and must appear before the first heading of the next higher level. This, for example, is an allowable hierarchy:\n",
    "\n",
    "    # Notebook Title\n",
    "    ## First section\n",
    "    ### First subsection\n",
    "    #### First sub-subsection\n",
    "    #### Second sub-subsection\n",
    "    ### Second subsection\n",
    "    ## Second section\n",
    "    ### Another subsection\n",
    "    \n",
    "This is not allowable because it skips from `##` to `####` without an intervening `###`:\n",
    "\n",
    "    # Notebook Title\n",
    "    ## First section\n",
    "    #### First sub-subsection\n",
    "    #### Second sub-subsection\n",
    "    ### Second subsection\n",
    "    ## Second section\n",
    "    ### Another subsection\n",
    "    \n",
    "The following guidelines apply to headings and subheadings:\n",
    "    \n",
    "* Following the Chicago Manual of Style, only the first word in headings and subheadings are capitalized.\n",
    "* Each heading or subheading appears as the first line in a markdown cell.\n",
    "* At this point in the development this style guide, titles, headings, and subheadings should remain unnumbered."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Keywords\n",
    "\n",
    "Keywords should be included in the level 1 headers designating a title. The keywords are specified in a new line beginning with `Keywords:` followed by a comma separated list of keyword phrases. Keywords are used to construct an index for the notebook collection."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## External Files\n",
    "\n",
    "Notebooks will often incorporate figures, data, or video. Any external files must be appropriately licensed for reuse. If that isn't possible, then that information should be accessed by linking to a resource showing the user how to properly access that information.\n",
    "\n",
    "In general, external resources should be referenced by an external link whenever possible. If the resource is in the same repository, the link should be the public repository. This practice enables cross-platform use of notebooks, and streamlines the import and use of notebooks by other users."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Figures\n",
    "\n",
    "Figures included within the repository should located within a common figures directory. This practice enables reuse of figures, and streamlines the editing and maintenance of figures. Figures should be `.png` or `.jpg` format as appropriate, and resized for use with the standard markdown `![]()` markup."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Data\n",
    "\n",
    "Data files distributed with the repository should be located within a common data directory. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Design for Portability\n",
    "\n",
    "Notebooks are intended as durable and robust means of communicating with a diverse audience. To this end, special effort attention must be given to making it possible to run the notebooks on multiple platforms. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Installations and Imports\n",
    "\n",
    "It is good practice to include all necessary installations and imports in first few executable cells of a notebook, and may be included in a special section entitled **Installations and imports**.\n",
    "\n",
    "To the extent possible, the installation and import cells should be written to run cross-platform without raising exceptions. Code can written with the assumption that standard Python libraries, including Matplotlib, Numpy, Pandas, and Scipy, are present. Any needed installations should included in the first code cell of the notebook and written for cross-platform use. For example,\n",
    "\n",
    "    import sys\n",
    "    if 'google.colab' in sys.modules:\n",
    "        !pip install pyomo\n",
    "        !pin install glpk\n",
    "        \n",
    "Conditional installs may have been previously installed on the user's computer.\n",
    "\n",
    "    try:\n",
    "        import glpk\n",
    "    except\n",
    "        !pip install glpk\n",
    "        import glpk"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Markdown\n",
    "\n",
    "Plain github-flavored markdown should be used wherever possible. Avoid use of non-markdown constructs, such as html tags.\n",
    "\n",
    "* Any references should be collected under a separate heading entitled References, and formatted using the Chicago Manual of Style.\n",
    "* Additional sections entitled Exercises, Additional resources, Further reading may be included in the notebooks. Each exercise should be given a separate subsection to be included in the table of contents."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Further reading"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* [Space Telescope Science Institute Style Guide](https://github.com/spacetelescope/style-guides/blob/master/guides/jupyter-notebooks.md)\n",
    "* [Jupyter notebook best practices and style guide](https://github.com/chrisvoncsefalvay/jupyter-best-practices)\n",
    "* [Dataquest: An In-Depth Style Guide for Data Science Projects](https://www.dataquest.io/blog/data-science-project-style-guide/)\n",
    "* [ESRI: Coding Standards for Jupyter Notebook](https://www.esri.com/about/newsroom/arcuser/coding-standards-for-jupyter-notebook/)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}