GCC documentation: porting to Sphinx

[Joseph Myers]

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

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

-- 
Joseph S. Myers
joseph@codesourcery.com