mirror of
https://github.com/ImperialCollegeLondon/ReCoDE_MCMCFF.git
synced 2025-06-26 08:51:16 +02:00
3443455cf9
- Replaces references to `code` to `src` - Adds language attributes to fenced code blocks - Updates output of `setup.cfg` in notebook 2. - Fixes spelling and grammar errors
243 lines
8.2 KiB
Plaintext
243 lines
8.2 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",
|
|
"References:\n",
|
|
"- [Intro to basic ReStrutured Text](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)\n",
|
|
"- [Getting started with Sphinx](https://www.sphinx-doc.org/en/master/usage/quickstart.html)\n",
|
|
"\n",
|
|
"If we produce software that might be used by others even colleagues, it's imperative to document how it works and should be used. \n",
|
|
"\n",
|
|
"The classic way to do this in the python community is to use a tool called [Sphinx](https://www.sphinx-doc.org/en/master/), you'll probably be quite familiar with pages generated by Sphinx if you've ever used any python packages. To give you teaser by the end of this chapter we will have an autogenerated website for the project that looks like [this](https://recode-mcmcff.readthedocs.io/en/latest/)\n",
|
|
"\n",
|
|
"<div style=\"margin:auto;max-width:800px;\">\n",
|
|
"<img src=\"../_static/readthedocs_screenshot.png\" alt=\"A screenshot of the read the docs page linked above\"/>\n",
|
|
"</div>"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "d38dc6d6-3fe8-4ddf-b361-616c21c494dd",
|
|
"metadata": {},
|
|
"source": [
|
|
"We'll use sphinx along with a couple plugins: [autodoc][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",
|
|
"What this means is that we'll be able to write documentation directly into the source code, and it will get rendered into a nice website. This helps keep the documentation up to date because it's right there next to the code!\n",
|
|
"\n",
|
|
"[autodoc]: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html\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": "84f615bb-307e-428a-a6e2-07b5cc670bc1",
|
|
"metadata": {},
|
|
"source": [
|
|
"This means that the part of our source code that looks like: \n",
|
|
"<div style=\"margin:auto;max-width:800px;\">\n",
|
|
"<img src=\"../_static/sourcecode_screenshot.png\" alt=\"A screenshot of lines 50-77 of MCFF/mcmc.py\"/>\n",
|
|
"</div>\n",
|
|
"\n",
|
|
"will get rendered to [this][readthedocs_api]:\n",
|
|
"\n",
|
|
"<div style=\"margin:auto;max-width:800px;\">\n",
|
|
"<img src=\"../_static/readthedocs_api_screenshot.png\" alt=\"A screenshot of the previous link showing what mcmc.py gets rendered to\"/>\n",
|
|
"</div>\n",
|
|
"\n",
|
|
"[readthedocs_api]: https://recode-mcmcff.readthedocs.io/en/latest/api_docs.html"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "99519bbc-6aa9-49f4-8919-f8c8f6e72191",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Installation\n",
|
|
"\n",
|
|
"Make sure sphinx is installed in the environment then make a folder called `docs/`, 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": [
|
|
"This will populate `docs` with a skeleton sphinx project, to tell sphinx where to find our code we'll add some lines to `conf.py`:\n",
|
|
"```python\n",
|
|
"import os\n",
|
|
"import sys\n",
|
|
"sys.path.insert(0, os.path.abspath('../src'))\n",
|
|
"#since conf.py is in docs/ the path ../src points to where our module is\n",
|
|
"```"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "64d55530-c21a-4bd3-b25a-9c7109541038",
|
|
"metadata": {},
|
|
"source": [
|
|
"We add the extensions by adding this to `conf.py` too:\n",
|
|
"```python\n",
|
|
"extensions = [\n",
|
|
" 'sphinx.ext.autodoc',\n",
|
|
" 'sphinx.ext.napoleon',\n",
|
|
"]\n",
|
|
"```"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "6d2d4a0f-adf2-4cc7-b220-8243635658d5",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Writing docstrings\n",
|
|
"Numpy style docstrings look like this:\n",
|
|
"\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",
|
|
"```\n",
|
|
"\n",
|
|
"I normally just copy and paste this and go from there, but there's a full description [here](https://numpydoc.readthedocs.io/en/latest/format.html). You can also check out the docstrings in MCFF."
|
|
]
|
|
},
|
|
{
|
|
"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",
|
|
"```"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "c771a57d-c802-429a-b051-1bd0364b9317",
|
|
"metadata": {},
|
|
"source": [
|
|
"Finally, we add a `readthedocs.yaml` file (which you can copy from the root of this repo) to tell readthedocs how to build our documentation. https://docs.readthedocs.io/en/stable/config-file/v2.html#packages"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "3843afa1-5c83-4328-bf8c-5e189dc4ee35",
|
|
"metadata": {},
|
|
"source": [
|
|
"And the documentation is now hosted [online!](https://recode-mcmcff.readthedocs.io/en/latest/#)"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "f127ab21-327b-4080-870a-efe58bdba429",
|
|
"metadata": {},
|
|
"source": [
|
|
"### Documentation Ideas\n",
|
|
"\n",
|
|
"Readthedocs can be a bit tricky to set up, it is also possible to use GitHub pages to accomplish something similar. Another idea is to include some simple copyable code snippets in a quickstart guide. This lets people get up and running your code more quickly than is they need to read the API docs to understand how to interact with your module."
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": 1,
|
|
"id": "849ed924-b78f-4969-b7a0-3465c824f261",
|
|
"metadata": {},
|
|
"outputs": [
|
|
{
|
|
"name": "stdout",
|
|
"output_type": "stream",
|
|
"text": [
|
|
"Author: Thomas Hodson\n",
|
|
"\n",
|
|
"Github username: T_Hodson\n",
|
|
"\n",
|
|
"Last updated: Mon Jul 18 2022\n",
|
|
"\n",
|
|
"Python implementation: CPython\n",
|
|
"Python version : 3.9.12\n",
|
|
"IPython version : 8.4.0\n",
|
|
"\n",
|
|
"Git hash: 03657e08835fdf23a808f59baa6c6a9ad684ee55\n",
|
|
"\n",
|
|
"Git repo: https://github.com/ImperialCollegeLondon/ReCoDE_MCMCFF.git\n",
|
|
"\n",
|
|
"Git branch: main\n",
|
|
"\n",
|
|
"Watermark: 2.3.1\n",
|
|
"\n"
|
|
]
|
|
}
|
|
],
|
|
"source": [
|
|
"%load_ext watermark\n",
|
|
"%watermark -n -u -v -iv -w -g -r -b -a \"Thomas Hodson\" -gu \"T_Hodson\""
|
|
]
|
|
}
|
|
],
|
|
"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.8.10"
|
|
},
|
|
"vscode": {
|
|
"interpreter": {
|
|
"hash": "f5403acae4671aac0ae5a29dd5903d33d0105a9e9d4148f755d3321f5023d387"
|
|
}
|
|
}
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 5
|
|
}
|