{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0cbcd12b-a30a-4aec-bc64-6ef6e89fc847",
   "metadata": {},
   "source": [
    "# Documentation Only Sites\n",
    "\n",
    "> How to create nbdev powered docs without a library!\n",
    "- order: 9"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "504ef133-7e39-4ef8-a9d5-35a9ca6fbb9b",
   "metadata": {},
   "source": [
    "## Background\n",
    "\n",
    "While nbdev is great for authoring software, you may wish to utilize the power of nbdev for the purposes of documenting existing code, or **use various utilities of nbdev without having to write a python library**. For example, you can use the following features of nbdev without creating a python package:\n",
    "\n",
    "- Custom [nbdev directives](../explanations/directives.ipynb) such as [`#|hide_line`](../explanations/directives.ipynb#hide_line).\n",
    "- Testing with `nbdev_test`.\n",
    "- Automated entity linking with [doclinks](best_practices.ipynb#reference-related-symbols-with-doclinks).\n",
    "- Rendering API documentation with [docments and show_doc](best_practices.ipynb#document-parameters-with-docments).\n",
    "\n",
    "## Setup\n",
    "\n",
    "To setup a documentation only site, you can follow these steps:\n",
    "\n",
    "1. Create a nbdev repo the usual way, using `nbdev_new`\n",
    "2. Remove library files\n",
    "\n",
    "```bash\n",
    "rm setup.py .github/workflows/test.yaml nbs/00_core.ipynb\n",
    "```\n",
    "\n",
    "3. Remove your library folder (this will be the `lib_path` field in `settings.ini`):\n",
    "\n",
    "```bash\n",
    "rm -rf <lib_path>\n",
    "```\n",
    "\n",
    "## Usage\n",
    "\n",
    "After setting up your project, you can use various nbdev utilities per usual:\n",
    "\n",
    "- `nbdev_preview` for previewing your site\n",
    "- `nbdev_test` for testing your docs locally\n",
    "- Custom [nbdev directives](../explanations/directives.ipynb) will be available to you (but you must be careful not to use irrelevant ones like `#|export`).\n",
    "- If you created your nbdev docs site on GitHub, GitHub Actions will publish your docs for you automatically [as described here](../explanations/docs.ipynb#Deploying-Docs-With-GitHub-Actions).\n",
    "- You can publish your docs on other platforms as described [here](../explanations/docs.ipynb#Deploying-Your-Docs-On-Other-Platforms)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6c7c8ede-f3af-417d-8aa6-7658b5052288",
   "metadata": {},
   "source": [
    "## Demo\n",
    "\n",
    "A minimal example of a documentation-only site is located [here](https://github.com/hamelsmu/nolib_nbdev)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "60e597c1-9950-4927-ae5a-79fcc46497bd",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "python3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}