[yt-dev] 3.0 Documentation

[Matthew Turk]

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
>