Should we package demos and documentation?

[jacklovell]

We have some of the demo scripts copied verbatim into the HTML documentation, but many are only available by cloning the git repository to a local directory and running the demo scripts from there. In the past when cloning from git was the only viable way to install Cherab this wasn't an issue, but with recent improvements in packaging its no longer necessary for Cherab users to touch the git repository at all. Users who simply run pip install cherab don't have access to the demos anywhere on their system.

I propose we package the demo scripts in the sdist and wheel package distributions which are uploaded to PyPI. Upon installation, they would be placed in $PREFIX/share/cherab/core/demos: this would be an exact replica of the demos script in the repository. Other sub-packages would install demos in a similar place, e.g. cherab-solps would install them in $PREFIX/share/cherab/solps/demos. Here $PREFIX is the environment prefix: /usr for system python, the path to a virtual environment for venvs or ~/.local for a --user install.

This would have two advantages:

1. No need to clone the git repository for users who don't intend to develop Cherab.
2. The demos will match the version of Cherab installed.

Point 2 is particularly significant, as it's very easy when working with virtual environments to end up with a different version of the Cherab package installed in an environment to whatever's in the local checkout of the Git repository. We also only publish online documentation for the most recently-released version of Cherab: users may have an older version installed and should be able to access the demos suitable for that version easily.

Speaking of documentation, we could potentially do a similar thing with the HTML documentation, by building it and installing a copy in $PREFIX/share/cherab/docs. But since that involves a compilation stage it's potentially more complicated for sdists.

It looks like we can accomplish this by using the data-files option to setuptools' setup() function in setup.py (see also the distutils documentation. I've discounted including the demos as package-data or adding them to MANIFEST.in, because the use case is slightly different: package data is additional non-python files that the package needs to function. The demos are the opposite: python files (but not ones we want to be importable) which depend on the package to run. Once disadvantage to using data-files is that installation using python setup.py install won't copy the files across, but that method of installation is discouraged nowadays and is no longer necessary for installing Cherab.

@CnlPepper the same approach would work for Raysect as it shares the repository structure and online documentation publishing method with Cherab.

[vsnever]

I like the idea. Regarding the folder structure, since subpackages may have their own documentation in the future, I think the demos and the docs should be separated at the cherab/ level:

$PREFIX/share/cherab/
├── demos/
│   ├── core/
│   ├── solps/
│   ├── jet/
│   ├── ...
├── docs/
│   ├── core/
│   ├── solps/
│   ├── jet/
│   ├── ...