There should be fully-functional example scripts that run using at least the dummy modules. These will be separate from unit tests. These example scripts will be executed and the code and their output will be rendered in the docs.
Related Problem
The examples now are not actually being run so they may use deprecated features/ break in the future/ without any indication to devs. The examples should be run as part of the build process with their output being captured and rendered to rtd. This also ensures they are agnostic of any user's environment. Devs should only commit stripped notebooks/ code with no output files or data etc and the build process will handle the rest. Note that this should not be confused with unit tests.
Considered Alternatives
I think this is quite a standard process but other suggestions are welcomed. I think the simplest would be to have everything in jupyter notebooks because we can easily have markdown, code and outputs in one file. A pre-commit hook can be used to strip the notebooks prior to pushing.
Feature Description
There should be fully-functional example scripts that run using at least the dummy modules. These will be separate from unit tests. These example scripts will be executed and the code and their output will be rendered in the docs.
Related Problem
The examples now are not actually being run so they may use deprecated features/ break in the future/ without any indication to devs. The examples should be run as part of the build process with their output being captured and rendered to rtd. This also ensures they are agnostic of any user's environment. Devs should only commit stripped notebooks/ code with no output files or data etc and the build process will handle the rest. Note that this should not be confused with unit tests.
Considered Alternatives
I think this is quite a standard process but other suggestions are welcomed. I think the simplest would be to have everything in jupyter notebooks because we can easily have markdown, code and outputs in one file. A pre-commit hook can be used to strip the notebooks prior to pushing.
Additional Context
No response
Contact Details
No response