This merge request moves all of the code demo snippets in the docs/ from their .rst files into individual Python files in docs/code_demos/. These are then included in the pages using the sphinx method literalinclude. This means that it is easier for us to spot formatting errors in these scripts, largely because now we can run them against flake8.
Description
For this to be achieved, a number of changes have been made to the directory structure in docs/ regarding Python files:
A new directory has been made to store demo scripts: docs/code_demos/, with individual directories within it for each page: e.g. docs/code_demos/load/
All existing demo scripts have been moved into their respective sub-directory within docs/code_demos/
All code snippets included in .rst files which were considered a complete script (i.e. included correct imports for it to work) have been put into individual Python scripts in their respective sub-directory within docs/code_demos/
Some additional changes have also been made to support these changes:
Many minor fixes have been made to code snippets and .rst files including these snippets
All code snippets which are in individual Python files within docs/code_demos/ have been updated to be flake8 compliant
The flake8 configuration has been updated to account for linting docs/code_demos/
Acceptance Criteria
[x] When building the docs locally with sphinx-build -a docs/ docs/_build, all pages which include code snippets should include the correct Python file
Summary
This merge request moves all of the code demo snippets in the
docs/
from their.rst
files into individual Python files indocs/code_demos/
. These are then included in the pages using the sphinx methodliteralinclude
. This means that it is easier for us to spot formatting errors in these scripts, largely because now we can run them againstflake8
.Description
For this to be achieved, a number of changes have been made to the directory structure in
docs/
regarding Python files:docs/code_demos/
, with individual directories within it for each page: e.g.docs/code_demos/load/
docs/code_demos/
.rst
files which were considered a complete script (i.e. included correct imports for it to work) have been put into individual Python scripts in their respective sub-directory withindocs/code_demos/
Some additional changes have also been made to support these changes:
.rst
files including these snippetsdocs/code_demos/
have been updated to beflake8
compliantflake8
configuration has been updated to account for lintingdocs/code_demos/
Acceptance Criteria
sphinx-build -a docs/ docs/_build
, all pages which include code snippets should include the correct Python file