[yt-dev] Move docs back into repo?

Sat Jan 25 06:40:43 PST 2014

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 <nathan12343 at gmail.com>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 <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
>>
>>
> _______________________________________________
> yt-dev mailing list
> yt-dev at lists.spacepope.org
> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20140125/e6233fbd/attachment.html>