[yt-dev] Move docs back into repo?

Sun Jan 26 15:23:46 PST 2014

Agreed. +1 on this suggestion.

On Sat, Jan 25, 2014 at 11:11 AM, Nathan Goldbaum <nathan12343 at gmail.com>wrote:

> +1 on inclusion via a copy.
>
>
> On Sat, Jan 25, 2014 at 7:18 AM, Brian O'Shea <bwoshea at gmail.com> wrote:
>
>> That seems very sensible.  +1.
>>
>>
>> On Sat, Jan 25, 2014 at 9:40 AM, Britton Smith <brittonsmith at gmail.com>wrote:
>>
>>> 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
>>>>
>>>>
>>>
>>> _______________________________________________
>>> yt-dev mailing list
>>> yt-dev at lists.spacepope.org
>>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>>
>>>
>>
>> _______________________________________________
>> yt-dev mailing list
>> yt-dev at lists.spacepope.org
>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>
>>
>
> _______________________________________________
> yt-dev mailing list
> yt-dev at lists.spacepope.org
> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>
>

-- 
Cameron Hummels
Postdoctoral Researcher
Steward Observatory
University of Arizona
http://chummels.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20140126/fe47ef43/attachment.htm>