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">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">http://yt-project.org/docs/dev/developing/building_the_docs.html</a></div>
<div><div><br>On Friday, January 24, 2014, j s oishi <<a href="mailto:jsoishi@gmail.com">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>