[yt-dev] 3.0 Documentation

Cameron Hummels chummels at gmail.com
Fri Dec 13 08:31:36 PST 2013


I know they are there, but I wasn't sure if that was secret enough so
snoopers don't discover the unfinished 3.0 docs.

What needs to be done in order to build the 3.0 docs now, so that they
appear on that page?


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

> On Fri, Dec 13, 2013 at 11:28 AM, Cameron Hummels <chummels at gmail.com>
> wrote:
> > 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?
>
> All documentation builds can be found here:
>
> http://yt-project.org/docs/
>
> -Matt
>
> >
> >
> > 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
> >
> > _______________________________________________
> > 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/dd32c499/attachment.html>


More information about the yt-dev mailing list