[yt-dev] 3.0 Documentation

Fri Dec 13 08:28:52 PST 2013

How do we go about doing this?  Something through yt.readthedocs.org?  Or a
secret URL on yt-project.org/docs/3.0test or something?

On Fri, Dec 13, 2013 at 9:24 AM, Matthew Turk <matthewturk at gmail.com> wrote:

> On Fri, Dec 13, 2013 at 11:21 AM, Cameron Hummels <chummels at gmail.com>
> wrote:
> > "... given that there is already so much that needs to be documented, I
> > don't think adding epsilon on top of that is a big deal."
> >
> > This is exactly the sentiment that I was trying to avoid.  The longer the
> > docs are out of date, the easier it is to justify not documenting that
> > newest push that one makes to the codebase.
>
> I agree with this, but as I noted before, I think we can have a build
> of the docs that is not linked from the main website until it is
> largely up to date.
>
> >
> >
> > I understand that things are busy with the unit refactor, but I would say
> > that as soon as it is accepted we should aim to have fully updated docs
> that
> > are viewable to the public.
> >
> > Matt, I can try to test the cookbook recipes if that makes it easier.
> >
> > Cameron
> >
> >
> >
> >
> >
> > On Fri, Dec 13, 2013 at 9:12 AM, Nathan Goldbaum <nathan12343 at gmail.com>
> > wrote:
> >>
> >> I agree with Matt.  If the 3.0 docs were only somewhat out of sync that
> >> would be one thing, but there's about a year's worth of work that needs
> to
> >> be covered before the docs are correct.
> >>
> >> I understand your concern about documenting new features, however given
> >> that there is already so much that needs to be documented, I don't think
> >> adding epsilon on top of that is a big deal.
> >>
> >> On Friday, December 13, 2013, Matthew Turk wrote:
> >>>
> >>> On Fri, Dec 13, 2013 at 10:37 AM, Cameron Hummels <chummels at gmail.com>
> >>> wrote:
> >>> > Sounds good, but I guess I don't understand why the 3.0 docs aren't
> yet
> >>> > buildable.  I can build them locally.  The only thing that prevented
> me
> >>> > from
> >>> > doing this is that I had to pip install the new bootstrap theme in
> >>> > order for
> >>> > them to not fail.  Is this what you mean, Kacper?
> >>> >
> >>> > I understand not wanting to have out of date docs available to the
> user
> >>> > base, but i'd love to get something up so people can document new
> >>> > changes to
> >>> > the code as they make them.
> >>>
> >>> I agree with having the docs, but I worry that having *incorrect* docs
> >>> will be more damaging, particularly to perception, than no docs.
> >>>
> >>> > Let me know if you need help on this, Matt.
> >>>
> >>> I definitely do!  The best way to get started is to go through the
> >>> cookbook and make sure all the recipes work; I did this at one point,
> >>> but I may have missed a few, and I know a few have been updated in the
> >>> 2.x repo.
> >>>
> >>> Today after the conference call I can devote some cycles to this.
> >>>
> >>> -Matt
> >>>
> >>> >
> >>> > Cameron
> >>> >
> >>> >
> >>> > On Fri, Dec 13, 2013 at 6:42 AM, Matthew Turk <matthewturk at gmail.com
> >
> >>> > wrote:
> >>> >>
> >>> >> Hi Cameron,
> >>> >>
> >>> >> Thanks for taking this on!  I think that we should definitely push
> up
> >>> >> some 3.0 docs (which it sounds like Kacper is working on) but I'm
> not
> >>> >> sure that we should link them *until* they are mostly up to date.
> >>> >> Fortunately the cookbook process and the IPython Notebook process
> >>> >> won't pass until they are, so that's good.
> >>> >>
> >>> >> Once the AGORA telecon is over today I should be able to spend some
> >>> >> time hitting the easy changes to the docs that should bring them
> >>> >> mostly up to speed.  One thing we'll need to do with 3.0 that we
> >>> >> haven't in the past is emphasize much more strongly the developer
> >>> >> aspects, as some areas of the code -- while cleaner -- are different
> >>> >> in some key ways.
> >>> >>
> >>> >> -MAtt
> >>> >>
> >>> >> On Thu, Dec 12, 2013 at 6:34 PM, Cameron Hummels <
> chummels at gmail.com>
> >>> >> wrote:
> >>> >> > Hello everyone,
> >>> >> >
> >>> >> > Now that the bulk of the development is moving over to the yt-3.0
> >>> >> > branch, I
> >>> >> > propose we have the yt-3.0 docs available on the website.  Right
> >>> >> > now, a
> >>> >> > yt-3.0 branch exists in the yt-doc repository, but there are very
> >>> >> > minor
> >>> >> > changes in it relative to the yt 2.x documentation.
>  Unfortunately,
> >>> >> > there is
> >>> >> > no public way to view these documentations aside from downloading
> >>> >> > the
> >>> >> > repository and building locally.  I think by putting the 3.0 docs
> on
> >>> >> > the
> >>> >> > webpage, it will make it more likely that people contribute docs
> >>> >> > when
> >>> >> > they
> >>> >> > contribute new code changes, whereas if we wait too long, the
> >>> >> > codebase
> >>> >> > may
> >>> >> > get considerably out of sync with the docs.
> >>> >> >
> >>> >> > I think this will only require a slight change to the buildbot
> >>> >> > targets
> >>> >> > by
> >>> >> > Kacper.  What do people think?
> >>> >> >
> >>> >> > Cameron
> >>> >> >
> >>> >> >
> >>> >> > --
> >>> >> > Cameron Hummels
> >>> >> > Postdoctoral Researcher
> >>> >> > Steward Observatory
> >>> >> > University of Arizona
> >>> >> > http://chummels.org
> >>> >> >
> >>> >> > _______________________________________________
> >>> >> > yt-dev mailing list
> >>> >> > yt-dev at lists.spacepope.org
> >>> >> > http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
> >>> >> >
> >>> >> _______________________________________________
> >>> >> yt-dev mailing list
> >>> >> yt-dev at lists.spacepope.org
> >>> >> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
> >>> >
> >>> >
> >>> >
> >>> >
> >>> > --
> >>> > Cameron Hummels
> >>> > Postdoctoral Researcher
> >>> > Steward Observatory
> >>> > University of Arizona
> >>> > http://chummels.org
> >>> >
> >>> > _______________________________________________
> >>> > yt-dev mailing list
> >>> > yt-dev at lists.spacepope.org
> >>> > http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
> >>> >
> >>> _______________________________________________
> >>> yt-dev mailing list
> >>> yt-dev at lists.spacepope.org
> >>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
> >>
> >>
> >> _______________________________________________
> >> yt-dev mailing list
> >> yt-dev at lists.spacepope.org
> >> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
> >>
> >
> >
> >
> > --
> > Cameron Hummels
> > Postdoctoral Researcher
> > Steward Observatory
> > University of Arizona
> > http://chummels.org
> >
> > _______________________________________________
> > yt-dev mailing list
> > yt-dev at lists.spacepope.org
> > http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
> >
> _______________________________________________
> yt-dev mailing list
> yt-dev at lists.spacepope.org
> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>

-- 
Cameron Hummels
Postdoctoral Researcher
Steward Observatory
University of Arizona
http://chummels.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20131213/4dc32533/attachment.htm>