<div dir="ltr">Agreed. +1 on this suggestion.</div><div class="gmail_extra"><br><br><div class="gmail_quote">On Sat, Jan 25, 2014 at 11:11 AM, Nathan Goldbaum <span dir="ltr"><<a href="mailto:nathan12343@gmail.com" target="_blank">nathan12343@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">+1 on inclusion via a copy.</div><div class="HOEnZb"><div class="h5"><div class="gmail_extra"><br><br><div class="gmail_quote">
On Sat, Jan 25, 2014 at 7:18 AM, Brian O'Shea <span dir="ltr"><<a href="mailto:bwoshea@gmail.com" target="_blank">bwoshea@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">That seems very sensible. +1.<br></div><div class="gmail_extra"><br><br><div class="gmail_quote"><div>
On Sat, Jan 25, 2014 at 9:40 AM, Britton Smith <span dir="ltr"><<a href="mailto:brittonsmith@gmail.com" target="_blank">brittonsmith@gmail.com</a>></span> wrote:<br>
</div><div><div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">Hey guys,<div><br></div><div>This discussion about building the docs is definitely worth having, but I think it is orthogonal to the question of whether to move the docs back into the source. How about we move the build discussion to a separate thread and focus here on where the docs should live?</div>
<div><br></div><div>So as far as I can tell, the only argument against merging docs into the source is the loss of history. What if we keep yt-doc around and make it read-only, so it can serve as an archive of the change history? It seems to me that the only people who would benefit from having doc history are developers of the docs and not really the readers. My proposal seems like it would serve any needs we might have regarding keeping the doc history. What do people think about this?</div>
<span><font color="#888888">
<div><br></div><div>Britton</div></font></span></div><div class="gmail_extra"><br><br><div class="gmail_quote"><div><div>On Sat, Jan 25, 2014 at 4:57 AM, Nathan Goldbaum <span dir="ltr"><<a href="mailto:nathan12343@gmail.com" target="_blank">nathan12343@gmail.com</a>></span> wrote:<br>
</div></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div>I agree. The ReadTheDocs version is mostly useful for doing a quick docs build to see what an addition to the docs look like. I was suggesting making the ReadTheDocs build mode more prominent since it allows quick iteration on the docs if one is only modifying the contents of an .rst file.<div>
<br></div><div>I don't think local docs builds or the ReadTheDocs build are particularly useful for actual reference. The former because it takes about a half hour to generate a full docs build and the latter because of the lack of API docs, recipe results, and evaluated notebooks.</div>
<div><br></div><div>Luckily, there is a full docs build at <a href="http://yt-project.org/docs/dev" target="_blank">yt-project.org/docs/dev</a> that is fully built and updated whenever the docs change. I think the availability of the dev docs build obviates a lot of the need to build the docs locally and completely supplants ReadTheDocs. In fact, I'd be for permanently redirecting our ReadTheDocs page to the dev docs build.</div>
<div><br></div><div>That said, there definitely is a potential barrier for adding a new notebook or recipe, as a quick example, since notebooks and cookbooks are only built in the full build.</div><div><br></div><div>I don't think that is a big problem in practice, since some of us keep local docs builds that we can use to test new additions and then report issues during the docs PR process.</div>
<div><br></div><div>If anyone is curious about doing a full docs build, there are instructions in the development section of the docs<span></span>: <a href="http://yt-project.org/docs/dev/developing/building_the_docs.html" target="_blank">http://yt-project.org/docs/dev/developing/building_the_docs.html</a></div>
<div><div>
<div><div><br>On Friday, January 24, 2014, j s oishi <<a href="mailto:jsoishi@gmail.com" target="_blank">jsoishi@gmail.com</a>> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<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>On Jan 24, 2014 8:33 PM, "Nathan Goldbaum" <<a>nathan12343@gmail.com</a>> wrote:<br type="attribution"><blockquote style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br><br>On Friday, January 24, 2014, Matthew Turk <<a>matthewturk@gmail.com</a>> wrote:<br><blockquote 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 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 </blockquote></div></blockquote></div></blockquote></div></div>
</div></div><br></div></div><div>_______________________________________________<br>
yt-dev mailing list<br>
<a href="mailto:yt-dev@lists.spacepope.org" target="_blank">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></div></blockquote></div><br></div>
<br>_______________________________________________<br>
yt-dev mailing list<br>
<a href="mailto:yt-dev@lists.spacepope.org" target="_blank">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></div></div><br></div>
<br>_______________________________________________<br>
yt-dev mailing list<br>
<a href="mailto:yt-dev@lists.spacepope.org" target="_blank">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><br></div>
</div></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><br><br clear="all"><div><br></div>-- <br>Cameron Hummels<div>Postdoctoral Researcher</div><div>Steward Observatory</div><div>University of Arizona</div><div><a href="http://chummels.org" target="_blank">http://chummels.org</a></div>
</div>