[yt-dev] 3.0 Documentation

Matthew Turk matthewturk at gmail.com
Fri Dec 13 08:33:42 PST 2013 

On Fri, Dec 13, 2013 at 11:31 AM, Cameron Hummels <chummels at gmail.com> wrote:
> 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.

Let me clarify: I am not interested in keeping things secret.  The
whole point is to avoid having someone go to the website, find the
link to a 3.0 build, and then see grossly, completely out of date
documentation pieces.  This is sufficient -- I just don't want a
dropdown to 3.0 on the main page.

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

I assume updating whatever the issues were that Kacper reported
earlier in the thread, which were mainly about the cookbook.

>
>
> 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
>
> _______________________________________________
> 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