<p dir="ltr">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. </p>

<p dir="ltr">J</p>
<div class="gmail_quote">On Jan 24, 2014 8:33 PM, "Nathan Goldbaum" <<a href="mailto:nathan12343@gmail.com">nathan12343@gmail.com</a>> wrote:<br type="attribution"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br><br>On Friday, January 24, 2014, Matthew Turk <<a href="mailto:matthewturk@gmail.com" target="_blank">matthewturk@gmail.com</a>> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

On Fri, Jan 24, 2014 at 3:52 PM, Cameron Hummels <<a>chummels@gmail.com</a>> wrote:<br>
><br>
><br>
>><br>
>> > 1) Dependencies.  Right now, there is a non-trivial amount of work<br>
>> > required<br>
>> > to build the docs in full (or even in part).  It isn't a matter of just<br>
>> > going into docs and typing `make html` with a vanilla yt installation.<br>
>> > If<br>
>> > you want to build all of the notebooks, you need extra libraries, some<br>
>> > of<br>
>> > them taking a decent amount of time to install.  Pandocs installation is<br>
>> > somewhat tricky (homebrew it isn't bad, but with macports, it is very<br>
>> > problematic), and I recall a lot of extra steps.  Anyway, if we're going<br>
>> > to<br>
>> > package the docs with code, should we include all of the docs<br>
>> > dependencies<br>
>> > in the yt installer?  Or just leave it to individuals to do this on<br>
>> > their<br>
>> > own?<br>
>><br>
>> Leave it to individuals, and make it a safe failure if the deps aren't<br>
>> there.<br>
>><br>
>> I mean, if we're relying on notebooks, the failsafe for not being able<br>
>> to turn them into docs is ... to run them in the notebook.  Right?<br>
>><br>
> Part of the reason I bring this up is, if one is still unable to build the<br>
> docs, then there is still a major hurdle to including documentation in PRs.<br>
> In fact, last time I submitted a change to the docs, I could not build the<br>
> docs because of all of the dependencies, so I just *hoped* that it rendered<br>
> OK before submission.  Clearly not an ideal situation.<br>
<br>
Agreed.  I actually don't know what to do about this.<br>
<br>
><br>
> Installing some of the dependencies, like SZPack or pandocs, is a pain.  So<br>
> I'd vote for following Nathan's advice to turn off building the api and<br>
> notebook builds by default with the "readthedocs" option.<br>
<br>
Okay.<br>
<br>
If we could get rid of pandoc as a dep, I think we'd be a lot further<br>
along.  I don't know how realistic that is.  SZPack I am much less<br>
concerned about.</blockquote><div><br></div><div>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.</div><div><br></div>Matt, what do you think about making the ReadTheDocs build the default?  <div>

<br></div><div>In any case, ReadTheDocs is always there and is mentioned in the docs section<span></span> on how to build the docs.<br><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">


<br>
><br>
>> ><br>
>> > 2) By my count, yt-docs (unbuilt) takes 41MB of space, with yt-hg taking<br>
>> > 113MB of space, so I think this is not going to break the bank to move<br>
>> > the<br>
>> > docs into the yt repo, as long as we continue to do mostly dynamically<br>
>> > generated images/movies/content.  If we start tracking lots of media<br>
>> > files,<br>
>> > it could bulk pretty fast.<br>
>><br>
>> I agree, and I am very nervous about that.  When you say it takes 41MB<br>
>> of space, are you counting the .hg directory?<br>
><br>
><br>
> Yes, I was including the .hg directory.  Without the .hg directory yt-doc is<br>
> 29MB, whereas yt-hg is 59MB, so it does add 50% to the size of the resulting<br>
> output.<br>
<br>
I am surprised we have 29MB of just stuff, without version history.  Hm.<br>
<br>
>><br>
>><br>
>> ><br>
>> > 3) What happens to the history of the docs in mercurial if we move them<br>
>> > into<br>
>> > the yt source repo?  Does it start everything at ground zero?  Or do we<br>
>> > retain the history of commits from the yt-doc repo?<br>
>><br>
>> My proposal was to simply import them en masse without retaining the<br>
>> history, but not to delete the old repository.<br>
><br>
><br>
> I guess that is OK, but it's too bad those old commits will be lost.  There<br>
> was some valuable information that got removed during the docs refactor a<br>
> few months ago, which it was easy to purge because the information isn't<br>
> lost in a version control system.  Now it will be.  Is there really no way<br>
> to merge repositories?  It seems like we could do either of these options:<br>
><br>
> <a href="http://hgtip.com/tips/advanced/2009-11-17-combining-repositories/" target="_blank">http://hgtip.com/tips/advanced/2009-11-17-combining-repositories/</a><br>
><br>
> <a href="http://mercurial.selenic.com/wiki/MergingUnrelatedRepositories" target="_blank">http://mercurial.selenic.com/wiki/MergingUnrelatedRepositories</a><br>
><br>
<br>
I am skeptical we will be happy with this, and it would likely require<br>
forcing a re-clone.  If the choice is between a grafting into a<br>
frankenstein repository and not putting the docs into the main repo,<br>
I'd go with not putting the docs in the main repo.  I understand not<br>
wanting to lose the commits, but we won't be -- they will just not be<br>
in the main repo where the current versions are.<br>
<br>
-Matt<br>
<br>
> Cameron<br>
>><br>
>><br>
>> ><br>
>> > Cameron<br>
>> ><br>
>> ><br>
>> > On Fri, Jan 24, 2014 at 11:48 AM, Brian O'Shea <<a>bwoshea@gmail.com</a>><br>
>> > wrote:<br>
>> >><br>
>> >><br>
>> >>> > +1.  I really like having the docs and the source in the same<br>
>> >>> > repository,<br>
>> >>> > for the reasons that you've listed.  Also, when I put yt on a new<br>
>> >>> > machine it<br>
>> >>> > makes it impossible for me to forget to also get the docs...  :-)<br>
>> >>><br>
>> >>> They do currently get checked out into<br>
>> >>> $YT_DEST/src/yt-supplemental/yt-doc , but we can get rid of that if we<br>
>> >>> move them back in.<br>
>> >><br>
>> >><br>
>> >> *facepalm*<br>
>> >><br>
>> >> Thanks!<br>
>> >><br>
>> >><br>
>> >> _______________________________________________<br>
>> >> yt-dev mailing list<br>
>> >> <a>yt-dev@lists.spacepope.org</a><br>
>> >> <a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br>
>> >><br>
>> ><br>
>> ><br>
>> ><br>
>> > --<br>
>> > Cameron Hummels<br>
>> > Postdoctoral Researcher<br>
>> > Steward Observatory<br>
>> > University of Arizona<br>
>> > <a href="http://chummels.org" target="_blank">http://chummels.org</a><br>
>> ><br>
>> > _______________________________________________<br>
>> > yt-dev mailing list<br>
>> > <a>yt-dev@lists.spacepope.org</a><br>
>> > <a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br>
>> ><br>
>> _______________________________________________<br>
>> yt-dev mailing list<br>
>> <a>yt-dev@lists.spacepope.org</a><br>
>> <a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br>
><br>
><br>
><br>
><br>
> --<br>
> Cameron Hummels<br>
> Postdoctoral Researcher<br>
> Steward Observatory<br>
> University of Arizona<br>
> <a href="http://chummels.org" target="_blank">http://chummels.org</a><br>
><br>
> _______________________________________________<br>
> yt-dev mailing list<br>
> <a>yt-dev@lists.spacepope.org</a><br>
> <a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br>
><br>
_______________________________________________<br>
yt-dev mailing list<br>
<a>yt-dev@lists.spacepope.org</a><br>
<a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br>
</blockquote></div>
<br>_______________________________________________<br>
yt-dev mailing list<br>
<a href="mailto:yt-dev@lists.spacepope.org">yt-dev@lists.spacepope.org</a><br>
<a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br>
<br></blockquote></div>