[yt-dev] Move docs back into repo?

Nathan Goldbaum nathan12343 at gmail.com
Fri Jan 24 17:33:07 PST 2014


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<javascript:;>>
> 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<javascript:;>
> >
> >> > 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 <javascript:;>
> >> >> 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 <javascript:;>
> >> > http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
> >> >
> >> _______________________________________________
> >> yt-dev mailing list
> >> yt-dev at lists.spacepope.org <javascript:;>
> >> 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 <javascript:;>
> > http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
> >
> _______________________________________________
> yt-dev mailing list
> yt-dev at lists.spacepope.org <javascript:;>
> 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/10e7e895/attachment.html>


More information about the yt-dev mailing list