Re: [boost] [GSoC] [Boost.Hana] Formal review request

Subject: Re: [boost] [GSoC] [Boost.Hana] Formal review request
From: Edward Diener (eldiener_at_[hidden])
Date: 2014-07-28 19:25:39

On 7/28/2014 4:37 PM, Louis Dionne wrote:
> Edward Diener <eldiener <at> tropicsoft.com> writes:
>
>>
>> On 7/28/2014 3:17 PM, Louis Dionne wrote:
>>>
>>> [...]
>>>
>>> As Glen points out, the tutorial is also written with Doxygen. You have to
>>> click on "Boost.Hana Manual" in the side bar at the left.
>>
>> I do not see this side bar on the left of your GitHub page.
>
> The side bar is in the documentation at
>
>      http://ldionne.github.io/hana
>
> , not on the GitHub page of the project itself.

I do see that.

>
>
>>> It should also be
>>> the landing page when you enter the documentation at:
>>>
>>>       http://ldionne.github.io/hana/
>>
>> I see this online. But in your instructions on your GitHub page you say
>> there is an offline version in the doc/gh-pages of your library but the
>> index.html there only shows the doxygen documentation.
>
> Just to make sure; did you do
>
>      git submodule update --init --remote

C:\Programming\VersionControl\modular-boost\libs\hana>git submodule 
update --init --remote
Submodule path 'doc/gh-pages': checked out 
'68817a886f0f13d286b28f27e4462694b37522b9'

I do now see the full manual. This is what I need to understand your 
library. Just a doxygen reference with examples never does anything for 
me <g>.

>
> at the root of your local clone, as instructed in the README? This checks out
> the doc/gh-pages submodule at its latest version. What I suspect you did is
> clone the project and then `git submodule init`, which would have left you
> with some fairly old version of the documentation.
>
> The `--remote` option must be added because the master branch only tracks the
> submodule at a given commit. I know of two solutions for this:
>
>      1. Use `git submodule update --init --remote` instead of the usual
>         `git submodule update --init` to check out the latest version of
>         the documentation.
>
>      2. Update the commit of the submodule referenced by the master branch
>         every time we regenerate the documentation in order to make
>         `git submodule update --init` equivalent to
>         `git submodule update --init --remote`.
>
> I went for the first option because I did not want to make a commit in master
> each time I updated the documentation. What I'll try to do for now is change
> the contents of doc/gh-pages that you get by default and put a note saying
>
>      "Here's the command you should do if you want the documentation offline"
>
> Does that seem reasonable?

A separate branch with the latest full documentation , maybe called 
'doc' might be clearer.