From 8fd35ba0bdfd5b64bcdf5bcf9ef784ae71f68706 Mon Sep 17 00:00:00 2001 From: Tom Hodson Date: Thu, 16 Jun 2022 17:02:32 +0200 Subject: [PATCH] Add sphinx docs --- .gitignore | 1 + code/docs/Makefile | 20 +++++ code/docs/_static/custom.css | 17 ++++ code/docs/_static/states.png | Bin 0 -> 56153 bytes code/docs/conf.py | 64 ++++++++++++++ code/docs/index.rst | 66 ++++++++++++++ code/docs/make.bat | 35 ++++++++ code/docs/requirements.txt | 0 code/src/MCFF/mcmc.py | 2 +- learning/09 API documentation.ipynb | 132 ++++++++++++++++++++++++++++ 10 files changed, 336 insertions(+), 1 deletion(-) create mode 100644 code/docs/Makefile create mode 100644 code/docs/_static/custom.css create mode 100644 code/docs/_static/states.png create mode 100644 code/docs/conf.py create mode 100644 code/docs/index.rst create mode 100644 code/docs/make.bat create mode 100644 code/docs/requirements.txt create mode 100644 learning/09 API documentation.ipynb diff --git a/.gitignore b/.gitignore index 99efc91..c7f9140 100644 --- a/.gitignore +++ b/.gitignore @@ -128,3 +128,4 @@ dmypy.json # Pyre type checker .pyre/ .DS_Store +_build/ diff --git a/code/docs/Makefile b/code/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/code/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/code/docs/_static/custom.css b/code/docs/_static/custom.css new file mode 100644 index 0000000..f44fe17 --- /dev/null +++ b/code/docs/_static/custom.css @@ -0,0 +1,17 @@ +/* This code comes from Yevhen Kuzmovych : https://github.com/sphinx-doc/sphinx/issues/1514#issuecomment-742703082 */ +/* Newlines (\a) and spaces (\20) before each parameter */ +.sig-param::before { + content: "\a\20\20\20\20\20\20\20\20\20\20\20\20\20\20\20\20"; + white-space: pre; +} + +/* Newline after the last parameter (so the closing bracket is on a new line) */ +dt em.sig-param:last-of-type::after { + content: "\a"; + white-space: pre; +} + +/* To have blue background of width of the block (instead of width of content) */ +dl.class > dt:first-of-type { + display: block !important; +} diff --git a/code/docs/_static/states.png b/code/docs/_static/states.png new file mode 100644 index 0000000000000000000000000000000000000000..6fd6db34fa76a387c026620b35799556593cdfd8 GIT binary patch literal 56153 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

dHpkO#PCH|#a}7}A#B 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 LZPQxg`$_)?WoSj4 literal 0 HcmV?d00001 diff --git a/code/docs/conf.py b/code/docs/conf.py new file mode 100644 index 0000000..f5b1ade --- /dev/null +++ b/code/docs/conf.py @@ -0,0 +1,64 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +sys.path.insert(0, os.path.abspath("../src/")) + + +# -- Project information ----------------------------------------------------- + +project = "MCFF" +copyright = "2022, Thomas Hodson" +author = "Thomas Hodson" + +# The full version, including alpha/beta/rc tags +release = "1.0" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "classic" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + +# These paths are either relative to html_static_path +# or fully qualified paths (eg. https://...) +html_css_files = [ + "custom.css", +] diff --git a/code/docs/index.rst b/code/docs/index.rst new file mode 100644 index 0000000..ec56a46 --- /dev/null +++ b/code/docs/index.rst @@ -0,0 +1,66 @@ +Imperial College London ReCoDE : Monte Carlo for Fun +==================================================== + +This is an exemplar project designed to showcase best practices in developing scientific software as part of the ReCoDE Project at Imperial College London. These docs have been generated automatically with sphinx. + +You can find the source code and main landing page for this project on `GitHub `_ + +There is a `Jupyter notebook `_ detailing how this page was generated in there. + + + +Quickstart +---------- + +.. code-block:: python + + from MCFF.mcmc import mcmc_generator + from MCFF.ising_model import show_state + + ### Simulation Inputs ### + N = 500 # Use an NxN system + + initial_state = np.random.choice( + np.array([-1, 1], dtype=np.int8), size=(N, N) + ) # the intial state to use + + ### Simulation Code ### + critical_states = [ + s for s in mcmc_generator(initial_state, steps=5, stepsize=5*N**2, T= 3.5) + ] + + fig, axes = plt.subplots( + ncols=len(critical_states), figsize=(5 * len(critical_states), 5) + ) + + for s, ax in zip(critical_states, axes): + show_state(s, ax=ax) + +.. image:: _static/states.png + :width: 100% + :alt: 5 grids showing black and white Ising Model states + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +mcmc : Markov Chain Monte Carlo Routines +--------------------------------------------- + +.. automodule:: MCFF.mcmc + :members: + +ising_model : Ising Model Routines +--------------------------------------------- + +.. automodule:: MCFF.ising_model + :members: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/code/docs/make.bat b/code/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/code/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/code/docs/requirements.txt b/code/docs/requirements.txt new file mode 100644 index 0000000..e69de29 diff --git a/code/src/MCFF/mcmc.py b/code/src/MCFF/mcmc.py index 8f85c57..215a786 100644 --- a/code/src/MCFF/mcmc.py +++ b/code/src/MCFF/mcmc.py @@ -67,7 +67,7 @@ def mcmc_generator( energy_difference : function(state, site), default = ising_model.energy_difference A function that gives the energy change from flippings `site = (i, j)`of `state`. - Returns + Yields ------- np.array The final state. diff --git a/learning/09 API documentation.ipynb b/learning/09 API documentation.ipynb new file mode 100644 index 0000000..d3fec75 --- /dev/null +++ b/learning/09 API documentation.ipynb @@ -0,0 +1,132 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "d3df99d5-0fd1-4912-aef2-26fc189917ec", + "metadata": {}, + "source": [ + "

Markov Chain Monte Carlo for fun and profit

\n", + "

๐ŸŽฒ โ›“๏ธ ๐Ÿ‘‰ ๐Ÿงช

\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 +}