doc/Makefile

doc: generate separate commands/topics/extension pages

This change modifies gendoc.py and Makefile so that individual pages for
commands, help topics, and extensions can be generated. A new index page is
also generated with links to all these pages. This makes it easier to look up
and search the help text of a given command or topic, instead of having to
deal with the giant hg.1 "all-in-one" page.

Since the list of individual pages varies based on the source code, we generate
a dynamic Makefile that contains this list of files as individual targets.
This gives us fine-grained control over output files. However, it greatly
increases the time spent generating all help pages. It's recommended to run
make with -j to make use of multi-core archs.

Individual man pages are produced in doc/man, and HTML ones are in doc/html

SOURCES=$(notdir $(wildcard ../mercurial/helptext/*.[0-9].txt))
MAN=$(SOURCES:%.txt=%)
HTML=$(SOURCES:%.txt=%.html)
GENDOC=gendoc.py ../mercurial/commands.py ../mercurial/help.py \
	../mercurial/helptext/*.txt ../hgext/*.py ../hgext/*/__init__.py
RUNRST=runrst
PREFIX=/usr/local
MANDIR=$(PREFIX)/share/man
INSTALL=install -m 644
# Default to Python 3.
#
# Windows ships Python 3 as `python.exe`, which may not be on PATH.  py.exe is.
ifeq ($(OS),Windows_NT)
PYTHON?=py -3
else
PYTHON?=python3
endif

RSTARGS=
GENDOCARGS=
GENDOCCMD=$(PYTHON) gendoc.py $(GENDOCARGS)

# Output directories for individual help pages.
MANOUT=man
HTMLOUT=html
BUILDDIR=build

export HGENCODING=UTF-8

.PHONY: all man html install clean knownrefs

# Generate a list of hg commands and extensions.
commandlist.txt: $(GENDOC)
	${GENDOCCMD} commandlist > $@.tmp
	mv $@.tmp $@

topiclist.txt: $(GENDOC)
	${GENDOCCMD} topiclist > $@.tmp
	mv $@.tmp $@

extensionlist.txt: $(GENDOC)
	${GENDOCCMD} extensionlist > $@.tmp
	mv $@.tmp $@

# Build target for running runrst more easily by hand
knownrefs: commandlist.txt topiclist.txt extensionlist.txt

BUILDFILES=commandlist.txt topiclist.txt extensionlist.txt

# We want to generate a sub-Makefile that can build the RST/man/html doc for
# each hg command. Here are templates that we'll use to generate this
# sub-Makefile.
HGCMDTPL=templates/cmdheader.txt
TOPICTPL=templates/topicheader.txt
EXTTPL=templates/extheader.txt

define RuleAllCommandsTemplate
HG_COMMANDS=$(1)
all-commands: $$(HG_COMMANDS:%=$$(BUILDDIR)/hg-%.gendoc.txt)
endef

define RuleAllTopicsTemplate
HG_TOPICS=$(1)
all-topics: $$(HG_TOPICS:%=$$(BUILDDIR)/%.gendoc.txt)
endef

define RuleAllExtensionsTemplate
HG_EXTENSIONS=$(1)
all-extensions: $$(HG_EXTENSIONS:%=$$(BUILDDIR)/%.gendoc.txt)
endef

define RuleCommandTemplate
$$(BUILDDIR)/hg-$C.gendoc.txt: $$(GENDOC) $$(HGCMDTPL)
	mkdir -p $$(@D)
	$${GENDOCCMD} cmd-$C > $$@.tmp
	mv $$@.tmp $$@
endef

define RuleTopicTemplate
$$(BUILDDIR)/topic-$T.gendoc.txt: $$(GENDOC) $$(TOPICTPL)
	mkdir -p $$(@D)
	$${GENDOCCMD} topic-$T > $$@.tmp
	mv $$@.tmp $$@
endef

define RuleExtensionTemplate
$$(BUILDDIR)/ext-$E.gendoc.txt: $$(GENDOC) $$(EXTTPL)
	mkdir -p $$(@D)
	$${GENDOCCMD} ext-$E > $$@.tmp
	mv $$@.tmp $$@
endef

# Actually generate the sub-Makefile.
# The $file function is only supported by GNU Make 4 and above.
CommandsTopicsExtensions.mk: commandlist.txt topiclist.txt extensionlist.txt Makefile
ifeq (4.0,$(firstword $(sort $(MAKE_VERSION) 4.0)))
	$(file > $@.tmp,# Generated by Makefile)
	$(file >> $@.tmp,$(call RuleAllCommandsTemplate,$(file < commandlist.txt)))
	$(file >> $@.tmp,$(call RuleAllTopicsTemplate,$(file < topiclist.txt)))
	$(file >> $@.tmp,$(call RuleAllExtensionsTemplate,$(file < extensionlist.txt)))
	$(foreach C,$(file < commandlist.txt),$(file >> $@.tmp,$(RuleCommandTemplate)))
	$(foreach T,$(file < topiclist.txt),$(file >> $@.tmp,$(RuleTopicTemplate)))
	$(foreach E,$(file < extensionlist.txt),$(file >> $@.tmp,$(RuleExtensionTemplate)))
	mv $@.tmp $@
else
	@echo "You are running make ${MAKE_VERSION} but you need make 4.0 or above"
endif

BUILDFILES+=CommandsTopicsExtensions.mk

# Include the sub-Makefile that contains rules for generating each individual
# command/help-topic/extension help page. This sub-Makefile is created by the
# rule above (CommandsTopicsExtensions.mk) which in turn is created from the
# plain-text lists of commands/help-topics/extensions.
#
# Any time the source code changes, these plain-text lists and this
# sub-Makefile will get regenerated. Make will then restart itself to take
# into account the rules inside the sub-Makefile.
#
# We want to avoid doing all this work for targets that we know don't need it
# however. For example, running `make clean` would only generate these files
# in order to delete them immediately. As a result, we don't include the
# sub-Makefile (and therefore don't require generating it) if clean is one of
# the targets. This might not do what we want when other targets are specified
# but it's most likely what we want.
ifeq (,$(filter clean,$(MAKECMDGOALS)))
-include CommandsTopicsExtensions.mk
endif

# If the sub-Makefile is available, add all the hg commands, help-topics, and
# extensions to the list of things to generate html and man pages for.
#
# Naming convention:
# - commands: hg-foo (html and man)
# - help topics: topic-foo (html), hgfoo (man)
# - extensions: ext-foo (html), hgext-foo (man)
#
# Man pages for commands are in section 1 (user commands), topics and 
# extensions are in section 7 (miscellanea)
#
# NOTE: topics and extension are temporarily disabled for man pages because
# they make docutils' RST converter crash.
ifdef HG_COMMANDS
HTML+=$(HG_COMMANDS:%=$(HTMLOUT)/hg-%.html)
MAN+=$(HG_COMMANDS:%=$(MANOUT)/hg-%.1)
endif

ifdef HG_TOPICS
HTML+=$(HG_TOPICS:%=$(HTMLOUT)/topic-%.html)
#MAN+=$(HG_TOPICS:%=$(MANOUT)/hg%.7)
endif

ifdef HG_EXTENSIONS
HTML+=$(HG_EXTENSIONS:%=$(HTMLOUT)/ext-%.html)
#MAN+=$(HG_EXTENSIONS:%=$(MANOUT)/hgext-%.7)
endif

# Also add the HTML index page
HTML+=$(HTMLOUT)/index.html


all: man html

man: $(MAN)

html: $(HTML)

# This logic is duplicated in setup.py:hgbuilddoc()
common.txt $(SOURCES) $(SOURCES:%.txt=%.gendoc.txt): $(GENDOC)
	${GENDOCCMD} "$(basename $@)" > $@.tmp
	mv $@.tmp $@

%: %.txt %.gendoc.txt common.txt $(RUNRST)
	$(PYTHON) runrst hgmanpage $(RSTARGS) --halt warning \
	  --strip-elements-with-class htmlonly $*.txt $*

%.html: %.txt %.gendoc.txt common.txt $(RUNRST)
	$(PYTHON) runrst html $(RSTARGS) --halt warning \
	  --link-stylesheet --stylesheet-path style.css $*.txt $*.html

# Rules for index page and individual command/help-topic/extension pages
# Because the naming isn't the same between html and man pages, we need to
# break down man pages rules a bit more.
$(BUILDDIR)/index.gendoc.txt: $(GENDOC)
	mkdir -p $(@D)
	${GENDOCCMD} index > $@.tmp
	mv $@.tmp $@

$(MANOUT)/hg-%.1: $(BUILDDIR)/hg-%.gendoc.txt common.txt $(RUNRST)
	mkdir -p $(@D)
	$(PYTHON) runrst hgmanpage --hg-individual-pages $(RSTARGS) --halt warning \
	  --strip-elements-with-class htmlonly $(BUILDDIR)/hg-$*.gendoc.txt $@

$(MANOUT)/hg%.7: $(BUILDDIR)/topic-%.gendoc.txt common.txt $(RUNRST)
	mkdir -p $(@D)
	$(PYTHON) runrst hgmanpage --hg-individual-pages $(RSTARGS) --halt warning \
	  --strip-elements-with-class htmlonly $(BUILDDIR)/topic-$*.gendoc.txt $@

$(MANOUT)/hgext-%.7: $(BUILDDIR)/ext-%.gendoc.txt common.txt $(RUNRST)
	mkdir -p $(@D)
	$(PYTHON) runrst hgmanpage --hg-individual-pages $(RSTARGS) --halt warning \
	  --strip-elements-with-class htmlonly $(BUILDDIR)/ext-$*.gendoc.txt $@

$(HTMLOUT)/%.html: $(BUILDDIR)/%.gendoc.txt common.txt $(RUNRST)
	mkdir -p $(@D)
	$(PYTHON) runrst html --hg-individual-pages $(RSTARGS) --halt warning \
	  --link-stylesheet --stylesheet-path style.css $(BUILDDIR)/$*.gendoc.txt $@

MANIFEST: man html
# tracked files are already in the main MANIFEST
	$(RM) $@
	for i in $(MAN) $(HTML); do \
	  echo "doc/$$i" >> $@ ; \
	done

install: man
	for i in $(MAN) ; do \
	  subdir=`echo $$i | sed -n 's/^.*\.\([0-9]\)$$/man\1/p'` ; \
	  mkdir -p "$(DESTDIR)$(MANDIR)"/$$subdir ; \
	  $(INSTALL) $$i "$(DESTDIR)$(MANDIR)"/$$subdir ; \
	done

# The clean target explicitly doesn't bother with the sub-Makefile, so we don't
# know anything about all the command/topic/extension targets and files.
# $(HTML) only has the basic topics, so we need to delete $(HTMLOUT)/*.html and
# other similar files "by hand" here.
clean:
	$(RM) $(MAN) $(HTML) common.txt $(SOURCES) MANIFEST *.gendoc.txt $(BUILDFILES) $(BUILDDIR)/*.gendoc.* $(HTMLOUT)/*.html