Documentation for dendro-core

[astrofrog]

We need to include documentation for dendro-core. One question I have is whether we should keep this separate from the dendrodocs, which covers more than just the Python version.

I think we had decided before that actually it would be best to only really have to maintain one reference implementation, and that we would go with Python, so one thing we could do is have this repository have its own proper documentation as if it was an independent package, then we can move the dendrodocs to a separate repository in this organization, prominently feature the Python package, and include information about the IDL and C++ codes as alternatives, indicating that the main reference implementation is the Python one.

@ChrisBeaumont @bradenmacdonald @low-sky - what do you think? If that sounds reasonable to you I can start working on the documentation for the core package itself?

[ChrisBeaumont]

+1 on moving towards discussion of a single set of code in the docs. I'm contacted about advice regarding dendrograming once every month or two, and it's always a mess trying to explain the state of things.

I would prefer that the dendro docs page continue to exist until the python implementation has viz + analysis routines. Then, I don't care whether the dendro docs are merged, reworked, or replaced -- especially since, if we buy a domain name, we can always put the "best" docs at docs.dendrograms.org or equivalent.

[astrofrog]

Ok, that sounds good - so then we should start a fresh set of docs here, right? If so, I'll start working on that.

[low-sky]

I'm aligned with this plan. I think that the IDL implementations will still have some users even after the python release, but it shouldn't be a supported route past what already exists. Thus, the "reference" implementation would be the right attitude to take in this situation.

[astrofrog]

I've created an initial documentation for the dendro-core package. I've made this issue into a pull request, and you can see the latest version of my branch here:

https://dendrograms-astrofrog.readthedocs.org/en/latest/

This is only a first draft - comments welcome at this stage! I think we need to add visual examples, etc.

[ChrisBeaumont]

One quick comment: I think diagrams like the first few on this page http://the-dendrodocs.readthedocs.org/en/latest/cookbook.html

help digest the hierarchy

On Thu, Jun 13, 2013 at 10:21 AM, Thomas Robitaille < notifications@github.com> wrote:

I've created an initial documentation for the dendro-core package. I've made this issue into a pull request, and you can see the latest version of my branch here:

https://dendrograms-astrofrog.readthedocs.org/en/latest/

This is only a first draft - comments welcome at this stage! I think we need to add visual examples, etc.

— Reply to this email directly or view it on GitHubhttps://github.com/dendrograms/dendro-core/pull/12#issuecomment-19394774 .

---

Chris Beaumont Graduate Student Institute for Astronomy University of Hawaii at Manoa 2680 Woodlawn Drive Honolulu, HI 96822 www.ifa.hawaii.edu/~beaumont

---

[astrofrog]

I agree - can I use the ones from dendrodocs?

[ChrisBeaumont]

Yes, the images (and illustrator file, if you want to tweak) are at https://github.com/ChrisBeaumont/DendroDocs

[astrofrog]

@ChrisBeaumont - I've updated the docs with a diagram:

https://dendrograms-astrofrog.readthedocs.org/en/latest/

and have updated the description of the Structure API to reflect the latest changes. Let me know if you have any suggestions at this point! The docs don't have to be perfect at this stage though, since things are still in flux, so we could consider merging this soon and then improving on it iteratively.

[ChrisBeaumont]

This is great. I think we could add some equivalent features to the compute documentation, which would clarify things quite a bit. But that can be an iterative improvement.