Makefile

# ----------------------------------------------------------------------
# List of translated languages
#
# Add a new language here and type "make" to generate new po files to
# translate.
# ----------------------------------------------------------------------
languages = ja

# ----------------------------------------------------------------------
# Important locations in the Spack submodule within this repo
# ----------------------------------------------------------------------
# rst source location
source_dir = spack/lib/spack/docs

# location of spack module for sphinx-apidoc
apidoc_dir = spack/lib/spack/spack

# ----------------------------------------------------------------------
# Other important top-level directories
# ----------------------------------------------------------------------
#
# templates
#     per-rst-file .pot template files generated by Sphinx, as well as
#     a single `merged.pot` file that combines them all into one.
#
# translations
#     Contains per-language .po files generated from the merged.pot
#     file. Simply edit these files to add translated strings to the
#     docs.  Also contains per-language .mo files generated from the
#     .po files (these are binary files needed by gettext).
#
# locale
#     We make per-rst-file symlinks back to .mo files in this directory.
#     You can then set locale_dirs = <path to locale> for Sphinx, and
#     it can generate internationalized documentation.
#
# docs
#     Per-language symlink trees back to the $source_dir. These are
#     used to set up this repository as different  ReadTheDocs projects.
#
# html
#     Builds of each of the per-language docs directories.  This isn't
#     actually used by ReadTheDocs, but it is what this Makefile
#     ultimately generates, so you can test the doc build locally.

# ----------------------------------------------------------------------
# Definitions of lists of important filenames per the above description
# ----------------------------------------------------------------------
# command to run sphinx-apidoc (add -n for dry run)
apidoc_cmd = sphinx-apidoc --no-toc -o $(source_dir) $(apidoc_dir) "*_spack_root*"

# command to symlink doc trees into place
link_docs_cmd = spack/bin/spack python scripts/link-docs.py

# location of all rst files in the documentation directory
generated_sources = $(sort \
	$(source_dir)/command_index.rst \
	$(shell $(apidoc_cmd) -n | egrep -o 'spack/.*rst'))

# main documentation sources (excluding generated docs, which may or may not be present)
sources = $(filter-out $(generated_sources),$(wildcard $(source_dir)/*.rst))

# all documnetation sources
all_sources = $(sort $(sources) $(generated_sources))

# base names of rst files
basenames = $(basename $(notdir $(all_sources)))

# template file names (there is one of these per initial .rst file)
pot_files = $(addprefix templates/,$(addsuffix .pot,$(basenames)))

# To simplify translation, we merge all the pot files into a single pot file
# This avoids duplicate strings and reduces work for translators
merged_pot = templates/merged.pot

# per-language translation file names
po_files = $(addprefix translations/,$(addsuffix .po,$(languages)))
mo_files = $(addprefix translations/,$(addsuffix .mo,$(languages)))

# per-language html translation directories
html_dirs = $(addprefix html/,$(languages))

# per-language sphinx build directories
docs_dirs = $(addprefix docs/,$(languages))

# we create per-file symlinks to each merged .po and .mo file so that Sphinx
# can use them.
fake_po_files = $(foreach lang,$(languages), \
	$(addprefix locale/$(lang)/LC_MESSAGES/,$(addsuffix .po,$(basenames))))
fake_mo_files = $(foreach lang,$(languages), \
	$(addprefix locale/$(lang)/LC_MESSAGES/,$(addsuffix .mo,$(basenames))))

# ----------------------------------------------------------------------
# Build rules
# ----------------------------------------------------------------------
# default target builds all docs
all: $(html_dirs) $(docs_dirs)

po: $(po_files) $(fake_po_files)
mo: $(mo_files) $(fake_mo_files)

templates/%.pot: $(source_dir)/%.rst
	@echo BUILD $(pot_files)
	@sphinx-build -b gettext $(source_dir) templates
	touch templates/*.pot  # make sure all pot files are updated

# generate a single, merged pot file from all pot template files
gettext: $(merged_pot)
$(merged_pot): $(pot_files)
	@echo MERGE $@
	msgcat -o $@ $^
	@sed -i~ 's/Report-Msgid-Bugs-To: [^"]*/Report-Msgid-Bugs-To: maintainers@spack.io\\n/' $@

# Make language-specific .po files from the merged pot file
# can be invoked as `make update` or just `make po`
update: $(po_files)
translations/%.po: $(merged_pot)
	@echo UPDATE $@
	@mkdir -p $(dir $@)
	@if [ ! -f $@ ] ; then msginit --no-translator -i $< -o $@ -l $*; fi
	@msgmerge -q --no-fuzzy-matching --previous -U $@ $<

# These are all symlinks to merged po files -- we do them per-file so
# Sphinx can use them
fake_po_files: $(fake_po_files)
locale/%.po:
	$(eval lang := $(shell echo $@ | sed 's@locale/\(.*\)/LC_MESSAGES.*@\1@'))
	@echo LINK $@
	@mkdir -p $(dir $@)
	@ln -sf ../../../translations/$(lang).po $@

locale/%.mo:
	$(eval lang := $(shell echo $@ | sed 's@locale/\(.*\)/LC_MESSAGES.*@\1@'))
	@echo LINK $@
	@mkdir -p $(dir $@)
	@ln -sf ../../../translations/$(lang).mo $@

translations/%.mo: translations/%.po
	@echo "GEN $@"
	@msgfmt $< -o $@

html/%: docs/% $(mo_files) $(fake_mo_files)
	$(eval lang := $(shell echo $@ | sed 's@html/\(.*\)@\1@'))
	@echo BUILD docs for language: $(lang)
	@sphinx-build -b html $< $@

docs/%: $(sources)
	$(eval lang := $(shell echo $@ | sed 's@docs/\(.*\)@\1@'))
	rm -rf $@
	mkdir -p $@
	$(link_docs_cmd) $(source_dir) $@
	sed -i~ 's/#language = None/language = "$(lang)"/' $@/conf.py
	sed -i~ 's@#locale_dirs = \[\]@locale_dirs = \["../../locale"\]@' $@/conf.py
	ln -s ../../spack docs/$(lang)/_spack_root

# remove everything not checked into git
clean:
	make -C $(source_dir) clean
	rm -rf html templates/.doctrees

# remove all generated files *except* translations, which we want to keep
clobber: clean
	rm -rf templates locale docs

# remove ALL generated files AND the translated .po files
# WARNING: this resets everything and starts from scratch
# YOU WILL LOSE YOUR TRANSLATIONS IF YOU RUN THIS
reset: clobber
	rm -rf translations