GCC documentation: porting to Sphinx

Martin Liška mliska@suse.cz
Thu Jun 24 14:08:16 GMT 2021


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


More information about the Gcc mailing list