{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "82bb4b40",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-19T02:31:58.662811Z",
     "iopub.status.busy": "2026-06-19T02:31:58.662573Z",
     "iopub.status.idle": "2026-06-19T02:32:01.221131Z",
     "shell.execute_reply": "2026-06-19T02:32:01.220383Z"
    },
    "tags": [
     "remove-cell"
    ]
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "An NVIDIA GPU may be present on this machine, but a CUDA-enabled jaxlib is not installed. Falling back to cpu.\n"
     ]
    }
   ],
   "source": [
    "%matplotlib inline\n",
    "import matplotlib.pyplot as plt\n",
    "import brainmass\n",
    "import brainstate\n",
    "import brainunit as u\n",
    "import jax\n",
    "import jax.numpy as jnp\n",
    "import numpy as np\n",
    "brainstate.environ.set(dt=0.1 * u.ms)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6ff3eeaa",
   "metadata": {},
   "source": [
    "# Documentation\n",
    "\n",
    "Guidelines for writing and building documentation.\n",
    "\n",
    "## Documentation Structure\n",
    "\n",
    "```text\n",
    "docs/\n",
    "├── index.rst               # Landing page\n",
    "├── api/                    # API reference\n",
    "│   ├── index.rst\n",
    "│   ├── models.rst\n",
    "│   └── ...\n",
    "├── tutorials/              # User tutorials\n",
    "│   ├── index.rst\n",
    "│   ├── quickstart.rst\n",
    "│   └── ...\n",
    "├── examples/               # Example notebooks\n",
    "│   ├── index.rst\n",
    "│   └── ...\n",
    "├── developer/              # Developer guide\n",
    "└── conf.py                 # Sphinx configuration\n",
    "```\n",
    "\n",
    "## Building Documentation\n",
    "\n",
    "Local build:\n",
    "\n",
    "```bash\n",
    "cd docs\n",
    "make html\n",
    "\n",
    "# Open in browser\n",
    "open _build/html/index.html  # macOS\n",
    "# or\n",
    "start _build/html/index.html  # Windows\n",
    "```\n",
    "\n",
    "Clean rebuild:\n",
    "\n",
    "```bash\n",
    "make clean\n",
    "make html\n",
    "```\n",
    "\n",
    "## Docstring Format\n",
    "\n",
    "Use Google-style docstrings:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "5c547ba1",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-19T02:32:01.224247Z",
     "iopub.status.busy": "2026-06-19T02:32:01.223722Z",
     "iopub.status.idle": "2026-06-19T02:32:01.227794Z",
     "shell.execute_reply": "2026-06-19T02:32:01.226927Z"
    }
   },
   "outputs": [],
   "source": [
    "def my_function(param1, param2, param3=None):\n",
    "    \"\"\"Brief one-line description.\n",
    "\n",
    "    Longer description with more details if needed.\n",
    "    Can span multiple paragraphs.\n",
    "\n",
    "    Args:\n",
    "        param1: Description of param1\n",
    "        param2: Description of param2 with units (Hz)\n",
    "        param3: Optional parameter, defaults to None\n",
    "\n",
    "    Returns:\n",
    "        Description of return value with shape and units\n",
    "\n",
    "    Raises:\n",
    "        ValueError: When param1 is negative\n",
    "\n",
    "    Examples:\n",
    "\n",
    "        >>> result = my_function(1.0, 2.0)\n",
    "        >>> print(result)\n",
    "        3.0\n",
    "\n",
    "    References:\n",
    "        Author et al. (2020). Paper Title. Journal.\n",
    "    \"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d4d32a9",
   "metadata": {},
   "source": [
    "## Writing Tutorials\n",
    "\n",
    "Tutorial structure:\n",
    "\n",
    "1. Clear objectives\n",
    "2. Prerequisites\n",
    "3. Step-by-step instructions\n",
    "4. Complete code examples\n",
    "5. Exercises or next steps\n",
    "\n",
    "### Example Tutorial Template\n",
    "\n",
    "```rst\n",
    "Tutorial Title\n",
    "==============\n",
    "\n",
    "Learn how to [objective].\n",
    "\n",
    "Prerequisites\n",
    "-------------\n",
    "- Knowledge of [topic]\n",
    "- Completed [previous tutorial]\n",
    "\n",
    "Overview\n",
    "--------\n",
    "This tutorial covers:\n",
    "1. Topic 1\n",
    "2. Topic 2\n",
    "3. Topic 3\n",
    "\n",
    "Step 1: [Title]\n",
    "---------------\n",
    "\n",
    "Explanation...\n",
    "\n",
    ".. code-block:: python\n",
    "\n",
    "   # Code example\n",
    "   import brainmass\n",
    "   model = brainmass.HopfStep(in_size=10)\n",
    "\n",
    "[More steps...]\n",
    "\n",
    "Next Steps\n",
    "----------\n",
    "- Try [exercise]\n",
    "- Read [related topic]\n",
    "```\n",
    "\n",
    "## Adding Examples\n",
    "\n",
    "Create Jupyter notebook in `examples/`:\n",
    "\n",
    "1. Name format: `###-descriptive-name.ipynb`\n",
    "2. Include clear markdown cells\n",
    "3. Add to appropriate gallery index\n",
    "4. Ensure it runs without errors\n",
    "\n",
    "## Documentation Style\n",
    "\n",
    "**Voice:**\n",
    "\n",
    "- Use second person (\"you\")\n",
    "- Active voice preferred\n",
    "- Clear and concise\n",
    "\n",
    "**Formatting:**\n",
    "\n",
    "- Code blocks for all code\n",
    "- Inline code for variables/functions\n",
    "- Bold for UI elements\n",
    "- Italics for emphasis (sparingly)\n",
    "\n",
    "**Links:**\n",
    "\n",
    "- Cross-reference related docs\n",
    "- Link to API documentation\n",
    "- External links where helpful\n",
    "\n",
    "## See Also\n",
    "\n",
    "- Sphinx documentation\n",
    "- MyST Markdown guide\n",
    "- {doc}`contributing` - Contribution process"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.13.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}