mirror of
https://github.com/ImperialCollegeLondon/ReCoDE_MCMCFF.git
synced 2025-06-26 08:51:16 +02:00
133 lines
3.7 KiB
Plaintext
133 lines
3.7 KiB
Plaintext
{
|
|
"cells": [
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "d3df99d5-0fd1-4912-aef2-26fc189917ec",
|
|
"metadata": {},
|
|
"source": [
|
|
"<h1 align=\"center\">Markov Chain Monte Carlo for fun and profit</h1>\n",
|
|
"<h1 align=\"center\"> 🎲 ⛓️ 👉 🧪 </h1>\n",
|
|
"\n",
|
|
"# Adding Documentation \n",
|
|
"\n",
|
|
"[Intro to basic Rst](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)\n",
|
|
"\n",
|
|
"[Getting started with Sphinx](https://www.sphinx-doc.org/en/master/usage/quickstart.html)"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "e2ecf10d-0025-4ce0-938a-807dbf0b6d1f",
|
|
"metadata": {},
|
|
"source": [
|
|
"Make a folder called `docs/` inside `code/`, cd into it and run sphinx\n",
|
|
"```sh\n",
|
|
"% mkdir docs\n",
|
|
"% cd docs\n",
|
|
"% sphinx-quickstart #just go with the defaults\n",
|
|
"```"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "7da17bd4-4072-4dd8-9680-dfd2a982de6f",
|
|
"metadata": {},
|
|
"source": [
|
|
"To tell sphinx where to find our code we add some lines to conf.py:\n",
|
|
"```python\n",
|
|
"import os\n",
|
|
"import sys\n",
|
|
"sys.path.insert(0, os.path.abspath('../src'))\n",
|
|
"```"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "64d55530-c21a-4bd3-b25a-9c7109541038",
|
|
"metadata": {},
|
|
"source": [
|
|
"We also add two extensions:\n",
|
|
"```python\n",
|
|
"extensions = [\n",
|
|
" 'sphinx.ext.autodoc',\n",
|
|
" 'sphinx.ext.napoleon',\n",
|
|
"]\n",
|
|
"```\n",
|
|
"\n",
|
|
"Autodoc allows us to generate documentation automatically from the docstrings in our source code, while [napoleon][napoleon] allows us to use [NUMPYDOC][numpydoc] and Google formats for the docstrings in addition to [reStructuredText][rst]\n",
|
|
"\n",
|
|
"[napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html\n",
|
|
"[NUMPYDOC]: https://numpydoc.readthedocs.io/en/latest/format.html\n",
|
|
"[googledoc]: https://google.github.io/styleguide/pyguide.html\n",
|
|
"[rst]: https://docutils.sourceforge.io/rst.html"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "6d2d4a0f-adf2-4cc7-b220-8243635658d5",
|
|
"metadata": {},
|
|
"source": [
|
|
"Numpy style docstrings look like this:\n",
|
|
"```python\n",
|
|
"def func(arg1, arg2):\n",
|
|
" \"\"\"Summary line.\n",
|
|
"\n",
|
|
" Extended description of function.\n",
|
|
"\n",
|
|
" Parameters\n",
|
|
" ----------\n",
|
|
" arg1 : int\n",
|
|
" Description of arg1\n",
|
|
" arg2 : str\n",
|
|
" Description of arg2\n",
|
|
"\n",
|
|
" Returns\n",
|
|
" -------\n",
|
|
" bool\n",
|
|
" Description of return value\n",
|
|
"\n",
|
|
" \"\"\"\n",
|
|
" return True\n",
|
|
"```"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "167d08ec-4c55-4050-929c-0ca5d4c03fd6",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Making the function declarations a bit nicer\n",
|
|
"Longer function names in the generated documentation currently generate with no line break, I found a fix for that buried [inside a bug report on sphinx](https://github.com/sphinx-doc/sphinx/issues/1514#issuecomment-742703082) \n",
|
|
"\n",
|
|
"It involves adding some custom css and an extra line to `conf.py`:\n",
|
|
"```python\n",
|
|
"html_css_files = [\n",
|
|
" 'custom.css',\n",
|
|
"]\n",
|
|
"```"
|
|
]
|
|
}
|
|
],
|
|
"metadata": {
|
|
"kernelspec": {
|
|
"display_name": "Python [conda env:recode]",
|
|
"language": "python",
|
|
"name": "conda-env-recode-py"
|
|
},
|
|
"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.12"
|
|
}
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 5
|
|
}
|