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

Subject: Re: [boost] [GSoC] [Boost.Hana] Formal review request
From: Louis Dionne (ldionne.2_at_[hidden])
Date: 2014-07-28 16:37:09

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.

> > 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

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?

Regards,
Louis