Re: GCC documentation: porting to Sphinx

["Martin Liška" <mliska@suse.cz>]

On 6/23/21 6:00 PM, Joseph Myers wrote:
> On Wed, 23 Jun 2021, Martin Liška wrote:
> 
>> @Joseph: Can you share your thoughts about the used Makefile integration? What
>> do you suggest for 2)
>> (note that explicit listing of all .rst file would be crazy)?
> 
> You can write dependencies on e.g. doc/gcc/*.rst (which might be more
> files than actually are relevant in some cases, if the directory includes
> some common files shared by some but not all manuals, but should be
> conservatively safe if you list appropriate directories there), rather
> than needing to name all the individual files.  Doing things with makefile
> dependencies seems better than relying on what sphinx-build does when
> rerun unnecessarily (if sphinx-build avoids rebuilding in some cases where
> the makefiles think a rebuild is needed, that's fine as an optimization).

All right. I've just done that and it was easier than I expected. Now the dependencies
are properly followed.

> 
> It looks like this makefile integration loses some of the srcinfo / srcman
> support.  That support should stay (be updated for the use of Sphinx) so
> that release tarballs (as generated by maintainer-scripts/gcc_release,
> which uses --enable-generated-files-in-srcdir) continue to include man
> pages / info files (and make sure that, if those files are present in the
> source directory, then building and installing GCC does install them even
> when sphinx-build is absent at build/install time).
> 

Oh, and I've just recovered this one as well. Pushed changes to the me/sphinx-v2
branch and I'm waiting for more feedback.

In the meantime, I'm going to prepare further integration of other manuals and
targets (PDF, HTML).

Martin