[yt-dev] 3.0 Documentation

Matthew Turk matthewturk at gmail.com
Fri Dec 13 08:29:40 PST 2013


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
>



More information about the yt-dev mailing list