From 88095cad41aa67ff82c51c2c26bc6ad387cae0ab Mon Sep 17 00:00:00 2001 From: Dan Allan Date: Wed, 5 Feb 2020 15:02:49 -0500 Subject: [PATCH] Illustrate literal-include and mention sphinx-gallery. --- docs/source/writing-docs.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/source/writing-docs.rst b/docs/source/writing-docs.rst index 7cf1f1e..73123ff 100644 --- a/docs/source/writing-docs.rst +++ b/docs/source/writing-docs.rst @@ -172,9 +172,30 @@ renders in HTML as: Try ``snell(0, 1, 1.33)``. +Embedded Scripts +^^^^^^^^^^^^^^^^ + +For lengthy examples with tens of lines or more, it can be convenient to embed +the content of a .py file rather than writing it directly into the +documentation. + +This can be done using the directive + +.. code-block:: rest + + .. literalinclude:: examples/some_example.py + +where the path is given relative to the current file's path. Thus, relative to +the repository's root directory, the path to this example script would be +``docs/source/examples/some_example.py``. + From here we refer you to the `sphinx code example documentation `_. +To go beyond embedded scripts to a more richly-featured example gallery that +shows scripts and their outputs, we encourage you to look at +`sphinx-gallery `_. + IPython Examples ^^^^^^^^^^^^^^^^