Announcement: Porting the Docs to Sphinx - 9. November 2022

[Jakub Jelinek]

On Thu, Oct 20, 2022 at 04:43:06PM +0000, Joseph Myers wrote:
> On Thu, 20 Oct 2022, Martin Liška wrote:
> 
> > > Also, but not strictly part of the release issue:
> > > 
> > > (d) Builds with missing or old Sphinx should work regardless of whether 
> > > such files are in the source directory - but if they aren't in the source 
> > > directory, the effect of missing or old Sphinx (detected at configure 
> > > time) should be to disable building and installing documentation.
> > 
> > All right Joseph, is it something you're willing to help me once we start
> > using Sphinx? Apparently, there will be many consequent steps after we switch.
> 
> Sure, but most of the conditionals are *already* present, just need 
> updating as part of the Sphinx transition.  E.g. gcc/Makefile.in has 
> BUILD_INFO and GENERATED_MANPAGES conditionals based on configure tests 
> for whether relevant tools are present and new enough; the rules for 
> $(DESTDIR)$(infodir)/%.info quietly allow the info files not to be 
> present, so installing also works without the info files or tools to build 
> them, and the rules for installing man pages similarly ignore errors; and 
> there are srcinfo and srcman rules, enabled based on @GENINSRC@, to copy 
> those built files to the source directory, which are what's used when 
> --enable-generated-files-in-srcdir is used as part of building a release 
> tarball.
> 
> The main thing I've suggested that I think may actually be new is an error 
> for trying to build a release tarball without new-enough Sphinx (I think 
> the current rules would quietly not copy info / man pages to the source 
> directory if build tools were missing - but having those tools missing 
> when building a release tarball is much less likely than not having 
> new-enough Sphinx).

But perhaps that test should go to maintainer-scripts/gcc_release.
Can be either of the form of checking if Sphinx is new enough, or checking
of make actually built the documentation before creating the tarballs.

	Jakub