{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "82872a20-aa42-48d7-a30d-2747749c916f",
   "metadata": {},
   "source": [
    "## Writing documentation and user guides\n",
    "\n",
    "We use [Sphinx](https://www.sphinx-doc.org/en/master/), and a few add-ons, most importantly [nbsphinx](https://nbsphinx.readthedocs.io/) so we can write using Jupyter notebooks."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c7e4d77-cec8-43b2-a379-3c372c8f5bf4",
   "metadata": {},
   "source": [
    "### Organisation\n",
    "\n",
    "The documentation mainly lives in the docs/source folder. This is the \"relevant\" high-level folder structure for the documentation:\n",
    "\n",
    "```\n",
    "├── docs                      <- Documentation folder.\n",
    "│   ├── build                 <- Placeholder for built docs.\n",
    "│   ├── source                <- Documentation scripts.\n",
    "│   │   ├── api               <- Files to render docstrings.\n",
    "│   │   ├── basics / websites <- Walkthrough notebooks.\n",
    "│   │   ├── index.rst         <- Main file.\n",
    "│   │   ├── contributing...   <- How to docs.\n",
    "│   │   └── etc.\n",
    "│   └── etc.                  <- Other necessary files.\n",
    "│\n",
    "└── etc.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b06deafd-c1c7-4b99-acc8-a4cadae50096",
   "metadata": {},
   "source": [
    "### Serving documentation locally\n",
    "\n",
    "It can be helpful to build and serve the documentation locally in order to QA any changes. \n",
    "\n",
    "To do so:\n",
    "\n",
    "1. Clone the repository\n",
    "   ```\n",
    "   git clone git@github.com:cmagovuk/selene-core.git\n",
    "   ```\n",
    "2. Activate your relevant environment\n",
    "   ```\n",
    "   conda activate py39\n",
    "   ```\n",
    "3. Navigate to the docs directory (the one with the Makefile), install requirements, pull submodules and build the html\n",
    "   ```\n",
    "   cd selene-core/docs\n",
    "   make requirements\n",
    "   make html\n",
    "   ```\n",
    "4. Run the docker image which serves the documentation\n",
    "   ```\n",
    "   make serve-start\n",
    "   ```\n",
    "5. For CMA users, in the browser URL, navigate to https://data.cma.gov.uk/leda/user/USERNAME/INSTANCENAME/proxy/80/index.html\n",
    "6. Update the documentation, re-run `make html` and refresh the page.\n",
    "7. To stop the container, run \n",
    "   ```\n",
    "   make serve-stop\n",
    "   ````"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f868a1b6-5ec8-40f7-bc4e-1a33f0950ce9",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.9",
   "language": "python",
   "name": "py39"
  },
  "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.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}