Re: [doc] Who copies doxygen-generated doc/html/reference for Sphinx?

From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2019-07-12 13:13:54

On Thu, 11 Jul 2019 at 23:44, Stefan Seefeld <stefan_at_[hidden]> wrote:
> On 2019-07-11 6:24 p.m., Mateusz Loskot wrote:
> >
> > The doxygen outputs files to doc/html/reference
> > The sphinx-build outputs to _build/html
> > The doc/index.rst expects the reference folder in _build/html/
> > but I can't find who copies the doc/html/reference into the _build/html
> > Where does it happen?
> > Or, does it not happen and simply deployment of re-generated API
> > reference has been overlooked?
>
> Good questions !
>
> Originally doxygen and sphinx were two tools that were used
> side-by-side, and the only cross-links were hard-coded (relative) URLs
> from the sphinx sources to the generated doxygen docs. It was manually
> tuned to fit the final layout.

I think that is still the case as per

```
API Reference <./reference/index.html#://>
```

(I don't quite get what is this `#://` at the end for)
in  https://github.com/boostorg/gil/blob/5ec5566fe43248bd4787119a9c54d794101c6a6b/doc/index.rst#L17

> As far as I can see from the doc/Makefile, _build isn't used at all for the "html" target, other than
> for the temporary doctrees.)

That is an important insight indeed.

Locally, I added the standard make.bat in order to allow  `make html`
on Windows and
to avoid failures due to missing `make` command.
I changed its BUILDDIR=html, then this `make clean` was deleting all
Doxygen-generated files:
https://github.com/boostorg/gil/blob/5ec5566fe43248bd4787119a9c54d794101c6a6b/doc/Jamfile#L59-L55
So, it turned out to be my mistake.

To summary:
The current `b2 doc` workflow is fine: first doxygen generates files
in doc/html,
then sphinx-build generates files in doc/html.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net