I am +1 for moving the docs into the main repo via copy and making the old
repo visible but read-only.
On Sat, Jan 25, 2014 at 6:40 AM, Britton Smith
Hey guys,
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?
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?
Britton
On Sat, Jan 25, 2014 at 4:57 AM, Nathan Goldbaum
wrote: 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.
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.
Luckily, there is a full docs build at yt-project.org/docs/dev 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.
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.
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.
If anyone is curious about doing a full docs build, there are instructions in the development section of the docs: http://yt-project.org/docs/dev/developing/building_the_docs.html
On Friday, January 24, 2014, j s oishi
wrote: 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.
J On Jan 24, 2014 8:33 PM, "Nathan Goldbaum"
wrote: On Friday, January 24, 2014, Matthew Turk
wrote: On Fri, Jan 24, 2014 at 3:52 PM, Cameron Hummels
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
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
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
just the 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.
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.
Matt, what do you think about making the ReadTheDocs build the default?
In any case, ReadTheDocs is always there and is mentioned in the docs section on how to build the docs.
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
_______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
_______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org