[yt-dev] Move docs back into repo?
Cameron Hummels
chummels at gmail.com
Fri Jan 24 12:52:18 PST 2014
> > 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.
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.
>
> > 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.
>
> >
> > 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
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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20140124/5c96cabd/attachment.html>
More information about the yt-dev
mailing list