[yt-dev] Move docs back into repo?

j s oishi jsoishi at gmail.com
Fri Jan 24 20:33:39 PST 2014


I know you agree asking Matt, but I personally find the read the docs
version to be nearly useless. Because it doesn't include the api docs, it
seems like every time I go looking for something, it isn't there. Worse,
there is no placeholder saying that they are incomplete. If you want an
example of what I mean, try looking in the Dev docs for what data objects
yt has. The "available objects" page gives a list, with a link to see more
info, like how to instantiate them. Follow that link on read the docs, and
it goes to a page that should have the api info but doesn't, and instead
gives a link *back* to the available objects page.

J
On Jan 24, 2014 8:33 PM, "Nathan Goldbaum" <nathan12343 at gmail.com> wrote:

>
>
> On Friday, January 24, 2014, Matthew Turk <matthewturk at gmail.com> wrote:
>
>> On Fri, Jan 24, 2014 at 3:52 PM, Cameron Hummels <chummels at gmail.com>
>> wrote:
>> >
>> >
>> >>
>> >> > 1) Dependencies.  Right now, there is a non-trivial amount of work
>> >> > required
>> >> > to build the docs in full (or even in part).  It isn't a matter of
>> just
>> >> > going into docs and typing `make html` with a vanilla yt
>> installation.
>> >> > If
>> >> > you want to build all of the notebooks, you need extra libraries,
>> some
>> >> > of
>> >> > them taking a decent amount of time to install.  Pandocs
>> installation is
>> >> > somewhat tricky (homebrew it isn't bad, but with macports, it is very
>> >> > problematic), and I recall a lot of extra steps.  Anyway, if we're
>> going
>> >> > to
>> >> > package the docs with code, should we include all of the docs
>> >> > dependencies
>> >> > in the yt installer?  Or just leave it to individuals to do this on
>> >> > their
>> >> > own?
>> >>
>> >> Leave it to individuals, and make it a safe failure if the deps aren't
>> >> there.
>> >>
>> >> I mean, if we're relying on notebooks, the failsafe for not being able
>> >> to turn them into docs is ... to run them in the notebook.  Right?
>> >>
>> > Part of the reason I bring this up is, if one is still unable to build
>> the
>> > docs, then there is still a major hurdle to including documentation in
>> PRs.
>> > In fact, last time I submitted a change to the docs, I could not build
>> the
>> > docs because of all of the dependencies, so I just *hoped* that it
>> rendered
>> > OK before submission.  Clearly not an ideal situation.
>>
>> Agreed.  I actually don't know what to do about this.
>>
>> >
>> > Installing some of the dependencies, like SZPack or pandocs, is a pain.
>>  So
>> > I'd vote for following Nathan's advice to turn off building the api and
>> > notebook builds by default with the "readthedocs" option.
>>
>> Okay.
>>
>> If we could get rid of pandoc as a dep, I think we'd be a lot further
>> along.  I don't know how realistic that is.  SZPack I am much less
>> concerned about.
>
>
> That would mean we'd need to abandon the notebooks -- nbconvert relies
> on pandoc heavily.  Needless to say, I's be strongly -1 on doing that.
>
> Matt, what do you think about making the ReadTheDocs build the default?
>
> In any case, ReadTheDocs is always there and is mentioned in the docs
> section on how to build the docs.
>
>
>>
>> >
>> >> >
>> >> > 2) By my count, yt-docs (unbuilt) takes 41MB of space, with yt-hg
>> taking
>> >> > 113MB of space, so I think this is not going to break the bank to
>> move
>> >> > the
>> >> > docs into the yt repo, as long as we continue to do mostly
>> dynamically
>> >> > generated images/movies/content.  If we start tracking lots of media
>> >> > files,
>> >> > it could bulk pretty fast.
>> >>
>> >> I agree, and I am very nervous about that.  When you say it takes 41MB
>> >> of space, are you counting the .hg directory?
>> >
>> >
>> > Yes, I was including the .hg directory.  Without the .hg directory
>> yt-doc is
>> > 29MB, whereas yt-hg is 59MB, so it does add 50% to the size of the
>> resulting
>> > output.
>>
>> I am surprised we have 29MB of just stuff, without version history.  Hm.
>>
>> >>
>> >>
>> >> >
>> >> > 3) What happens to the history of the docs in mercurial if we move
>> them
>> >> > into
>> >> > the yt source repo?  Does it start everything at ground zero?  Or do
>> we
>> >> > retain the history of commits from the yt-doc repo?
>> >>
>> >> My proposal was to simply import them en masse without retaining the
>> >> history, but not to delete the old repository.
>> >
>> >
>> > I guess that is OK, but it's too bad those old commits will be lost.
>>  There
>> > was some valuable information that got removed during the docs refactor
>> a
>> > few months ago, which it was easy to purge because the information isn't
>> > lost in a version control system.  Now it will be.  Is there really no
>> way
>> > to merge repositories?  It seems like we could do either of these
>> options:
>> >
>> > http://hgtip.com/tips/advanced/2009-11-17-combining-repositories/
>> >
>> > http://mercurial.selenic.com/wiki/MergingUnrelatedRepositories
>> >
>>
>> I am skeptical we will be happy with this, and it would likely require
>> forcing a re-clone.  If the choice is between a grafting into a
>> frankenstein repository and not putting the docs into the main repo,
>> I'd go with not putting the docs in the main repo.  I understand not
>> wanting to lose the commits, but we won't be -- they will just not be
>> in the main repo where the current versions are.
>>
>> -Matt
>>
>> > Cameron
>> >>
>> >>
>> >> >
>> >> > Cameron
>> >> >
>> >> >
>> >> > On Fri, Jan 24, 2014 at 11:48 AM, Brian O'Shea <bwoshea at gmail.com>
>> >> > wrote:
>> >> >>
>> >> >>
>> >> >>> > +1.  I really like having the docs and the source in the same
>> >> >>> > repository,
>> >> >>> > for the reasons that you've listed.  Also, when I put yt on a new
>> >> >>> > machine it
>> >> >>> > makes it impossible for me to forget to also get the docs...  :-)
>> >> >>>
>> >> >>> They do currently get checked out into
>> >> >>> $YT_DEST/src/yt-supplemental/yt-doc , but we can get rid of that
>> if we
>> >> >>> move them back in.
>> >> >>
>> >> >>
>> >> >> *facepalm*
>> >> >>
>> >> >> Thanks!
>> >> >>
>> >> >>
>> >> >> _______________________________________________
>> >> >> 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
>>
>
> _______________________________________________
> yt-dev mailing list
> yt-dev at lists.spacepope.org
> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20140124/748c1c7f/attachment.html>


More information about the yt-dev mailing list