Re: [yt-dev] Move docs back into repo?

25 Jan 2014

      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