[yt-dev] Move docs back into repo?

Matthew Turk matthewturk at gmail.com
Fri Jan 24 11:59:41 PST 2014


On Fri, Jan 24, 2014 at 2:57 PM, Cameron Hummels <chummels at gmail.com> wrote:
> I'm generally in favor of this, as it will lower the barrier to writing
> documentation, but I have a few questions.
>
> 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?

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

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

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



More information about the yt-dev mailing list