[yt-dev] Move docs back into repo?

[Nathan Goldbaum]

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 <jsoishi at gmail.com> 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" <nathan12343 at gmail.com> wrote:
>
>
>
> On Friday, January 24, 2014, Matthew Turk <matthewturk at gmail.com> wrote:
>
> 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.
>
>
> 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20140124/b87a8c47/attachment.html>