Documentation - Sphinx, jenkins, etc

[MartinHeroux]

Here is the post I mentioned during our call.

I used github pages to host the documentation of the first version of my spike2py packages. But I had to remember to go and regenerate the documentation manually every time I made additions or changes.

I did not have to write a jenkins file or anything. I simply followed a 3-part youtube video series of something walking me through the steps. But I would love to find a way to automate documentation generation/update (for example, after any merge of a pull request).

---

Do you see it as useful to include examples in user-facing classes, methods, functions?

For example, in the previous version of the spike2py package, I adopted a style I copied from ?? numpy...

"""Calibrate signal.
        Done when signal first created if `calibInfo` parameter provided.
        Calibrated signal will be available as `.proc`. However, it
        can also be performed after the signal has been created if the
        `slope` (and `offset`) parameters are provided. In this case, the
        calibration is applied `.proc` and stored in-place. `calibInfo`
        will be added to sig.
        See `CalibInfo` for details on `slope` and `offset`.
        Examples
        -------
        >>> import spike2py
        Calibrate signal after it has been created; slope only. Show `calibInfo`.
        >>> trial.sig['pressure'].calibrate(slope=-2.17)
        >>> trial.sig['pressure'].calibInfo
        CalibInfo(slope=-2.17, offset=None)
        Calibrate signal after it has been created; slope and intercept.
        Show `calibInfo`.
        >>> trial.sig['pressure'].calibrate(slope=-2.17, offset=-1.8)
        >>> trial.sig['pressure'].calibInfo
        CalibInfo(slope=-2.17, offset=-1.8)
        """

This would look nicely formatted when read in by Sphinx. But it does add a big chuck of text between a class/method declaration and the actual code. So it will help the user of the code, but might be distracting to someone working on the code itself.

Any thoughts?

[bbelderbos]

I personally find these big blocks annoying / distracting. If I look at code I want to look at code (which if well written should be self explanatory), and when I need more context I would go to the documentation. But that could be me. Of course doc tools rely on these docstrings but personally I would keep them short. Thanks for the link, added it to Pocket.