Should we AutoDoc the Documentation?

[gully]

The existing documentation and cookbook contains nice written descriptions of how the code works.

I have added some practical examples and figures to the documentation in Pull Request #23. However, every time I perform make html, I find that the new html content differs from the "live" html content in ways I did not expect. Specifically, the pages Grid Tools, Spectrum, Spectral Emulator, and Model contain API info from Autodoc.

As it stands, the new Autodoc API content looks cluttered, making it difficult to follow the descriptive text. I found a way to turn off the API content (by removing sphinx.ext.autodoc from the conf.py file). So I will do this, and the submit the new documentation content from PR #23.

But then the question is, should we have autodoc? I'm fairly agnostic on this point. But in principle, one could arrange it so that the descriptive content is at the top, and then the API class and method info is at the bottom. Or something sane like that.

I'll leave this here in case anyone has feelings either way.

[iancze]

Thank you very much for the nice examples you contributed! You are right that the original formatting of the autodoc'd API with the examples was somewhat haphazard, and the current formatting reads much more smoothly.

I do think we should use autodoc, because at least more often than not I end up browsing the API docs for a project. As frequently seems to be the case, can we borrow the format set by astropy? If I understand their docs, this would require putting the API references on their own pages.

On a related note, I noticed that on the gh-pages branch we have a 1.0/ folder for the documentation and a symbolic link from the current address. I will fix this to be consistent with the version throughout the rest of the project. Which brings me to another issue... I think it's time to create a roadmap for version development :)

[jason-neal]

Having the GridInterfaces autodoc'd would be very helpful. Or a mention that the grid interfaces automatically normalize and convert to air wavelengths in some cases would have been helpful somewhere.

I just spent a bunch of time troubleshooting why the grid_tools spectra were different (scaled and shifted) to the raw phoenix ones I manually loaded. They were automatically changed.

[gully]

Hi @jason-neal, I have been experimenting with some changes to Starfish's flux normalization assumptions. Depending on one's goals, the default behavior may not be adequate. Happy to chat about this. See Issue #38 for more info.