[yt-dev] Move docs back into repo?

Matthew Turk matthewturk at gmail.com
Fri Jan 24 17:20:21 PST 2014


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.

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



More information about the yt-dev mailing list