[SciPy-dev] Technology Previews and Sphinx Docstring Annotations

[Damian Eads]

Hi there,

Technology preview code is new code incorporated into the trunk of
SciPy, but may also appear into a future SciPy release at our option.
Such code is considered production grade and well-tested, but which
also has no guarantees of a stable API to enable further improvements
based on community feedback. The documentation will explicitly
indicate which packages, modules, and functions are part of the
technology preview.

Jarrod and I had a discussion on how to best annotate the RST of the
docstrings. One idea we came up with is to add a ".. techpreview"
keyword for use in an info.py file (packages), module-level docstring,
or function docstring. References in the index and detail
documentation are footnoted "Technology preview". We'd like to get
others to comment on the best way to annotate. Pauli: how easy would
it be to add an extra keyword for this purpose?

Thanks.

Cheers,

Damian


-----------------------------------------------------
Damian Eads                             Ph.D. Student
Jack Baskin School of Engineering, UCSC        E2-489
1156 High Street                 Machine Learning Lab
Santa Cruz, CA 95064    http://www.soe.ucsc.edu/~eads