taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

Makefile (8655B)


      1 # Makefile for Sphinx documentation
      2 #
      3 
      4 # You can set these variables from the command line.
      5 SPHINXOPTS    =
      6 SPHINXBUILD   = sphinx-build
      7 PYTHON        = python3
      8 PAPER         =
      9 BUILDDIR      = _build
     10 
     11 # User-friendly check for sphinx-build
     12 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
     13 $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. You can find Sphinx at http://sphinx-doc.org/)
     14 endif
     15 
     16 # Reproducible builds: every builder stamps the time of the build into its
     17 # output (the date in the .TH line of a manpage, \date{} in LaTeX, <dc:date>
     18 # and the zip entry times in the EPUB, POT-Creation-Date in the catalogs, the
     19 # /CreationDate of a PDF), so two builds of the same sources differ.  Sphinx
     20 # and pdftex both take that date from SOURCE_DATE_EPOCH when it is set, so pin
     21 # it to the commit date of HEAD.  A SOURCE_DATE_EPOCH already in the
     22 # environment or on the command line wins, which is what a distribution
     23 # building from a release tarball will provide; the fallback stays empty when
     24 # this is not a git checkout, as there is nothing better to use then.
     25 # conf.py repeats this for builds that invoke sphinx-build without make.
     26 ifeq ($(origin SOURCE_DATE_EPOCH), undefined)
     27 SOURCE_DATE_EPOCH := $(shell git log -1 --pretty=%ct 2>/dev/null)
     28 endif
     29 ifneq ($(strip $(SOURCE_DATE_EPOCH)),)
     30 export SOURCE_DATE_EPOCH
     31 # pdftex uses SOURCE_DATE_EPOCH for /CreationDate on its own, but only honours
     32 # it for \today and \pdfcreationdate if told to.
     33 export FORCE_SOURCE_DATE = 1
     34 endif
     35 
     36 # Internal variables.
     37 PAPEROPT_a4     = -D latex_paper_size=a4
     38 PAPEROPT_letter = -D latex_paper_size=letter
     39 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
     40 # the i18n builder cannot share the environment and doctrees with the others
     41 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
     42 
     43 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
     44 .PHONY: texinfo-exchange
     45 
     46 help:
     47 	@echo "Please use \`make <target>' where <target> is one of"
     48 	@echo "  html       to make standalone HTML files"
     49 	@echo "  dirhtml    to make HTML files named index.html in directories"
     50 	@echo "  singlehtml to make a single large HTML file"
     51 	@echo "  pickle     to make pickle files"
     52 	@echo "  json       to make JSON files"
     53 	@echo "  htmlhelp   to make HTML files and a HTML help project"
     54 	@echo "  qthelp     to make HTML files and a qthelp project"
     55 	@echo "  devhelp    to make HTML files and a Devhelp project"
     56 	@echo "  epub       to make an epub"
     57 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
     58 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
     59 	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
     60 	@echo "  text       to make text files"
     61 	@echo "  man        to make manual pages"
     62 	@echo "  texinfo    to make Texinfo files"
     63 	@echo "  info       to make Texinfo files and run them through makeinfo"
     64 	@echo "  gettext    to make PO message catalogs"
     65 	@echo "  changes    to make an overview of all changed/added/deprecated items"
     66 	@echo "  xml        to make Docutils-native XML files"
     67 	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
     68 	@echo "  linkcheck  to check all external links for integrity"
     69 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
     70 
     71 clean:
     72 	rm -rf $(BUILDDIR)/*
     73 
     74 .PHONY: diagrams
     75 diagrams:
     76 	$(MAKE) -C images/
     77 
     78 
     79 html: diagrams
     80 # -W = exit 1 on warning; --keep-going = complete build anyway; -w /tmp/sphinx-warnings.log = write log to ~/warnings.log
     81 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
     82 	@echo
     83 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
     84 
     85 dirhtml:
     86 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
     87 	@echo
     88 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
     89 
     90 singlehtml:
     91 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
     92 	@echo
     93 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
     94 
     95 pickle:
     96 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
     97 	@echo
     98 	@echo "Build finished; now you can process the pickle files."
     99 
    100 json:
    101 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
    102 	@echo
    103 	@echo "Build finished; now you can process the JSON files."
    104 
    105 htmlhelp:
    106 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
    107 	@echo
    108 	@echo "Build finished; now you can run HTML Help Workshop with the" \
    109 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
    110 
    111 qthelp:
    112 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
    113 	@echo
    114 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
    115 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
    116 	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/neuro.qhcp"
    117 	@echo "To view the help file:"
    118 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/neuro.qhc"
    119 
    120 devhelp:
    121 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
    122 	@echo
    123 	@echo "Build finished."
    124 	@echo "To view the help file:"
    125 	@echo "# mkdir -p $$HOME/.local/share/devhelp/neuro"
    126 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/neuro"
    127 	@echo "# devhelp"
    128 
    129 epub: diagrams
    130 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
    131 # Sphinx stamps the entries of the epub container with the modification times
    132 # of the files it just wrote, i.e. with the time of the build; this replaces
    133 # them with SOURCE_DATE_EPOCH, and is a no-op when that is unset.
    134 	$(PYTHON) contrib/reproducible-epub.py $(BUILDDIR)/epub/*.epub
    135 	@echo
    136 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
    137 
    138 latex: diagrams
    139 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
    140 	@echo
    141 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
    142 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
    143 	      "(use \`make latexpdf' here to do that automatically)."
    144 
    145 latexpdf: diagrams
    146 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
    147 	@echo "Running LaTeX files through pdflatex..."
    148 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
    149 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
    150 
    151 latexpdfja: diagrams
    152 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
    153 	@echo "Running LaTeX files through platex and dvipdfmx..."
    154 	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
    155 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
    156 
    157 text:
    158 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
    159 	@echo
    160 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
    161 
    162 man:
    163 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
    164 	@echo
    165 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
    166 
    167 texinfo:
    168 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
    169 	@echo
    170 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
    171 	@echo "Run \`make' in that directory to run these through makeinfo" \
    172 	      "(use \`make info' here to do that automatically)."
    173 
    174 texinfo-exchange:
    175 	$(SPHINXBUILD) -b texinfo . $(BUILDDIR)/texinfo-exchange ./taler-bank.rst -D master_doc=taler-exchange
    176 	@echo
    177 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo-exchange."
    178 	@echo "Run \`make' in that directory to run these through makeinfo"
    179 
    180 info:
    181 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
    182 	@echo "Running Texinfo files through makeinfo..."
    183 	make -C $(BUILDDIR)/texinfo info
    184 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
    185 
    186 gettext:
    187 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
    188 	@echo
    189 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
    190 
    191 changes:
    192 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
    193 	@echo
    194 	@echo "The overview file is in $(BUILDDIR)/changes."
    195 
    196 linkcheck:
    197 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
    198 	@echo
    199 	@echo "Link check complete; look for any errors in the above output " \
    200 	      "or in $(BUILDDIR)/linkcheck/output.txt."
    201 
    202 doctest:
    203 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
    204 	@echo "Testing of doctests in the sources finished, look at the " \
    205 	      "results in $(BUILDDIR)/doctest/output.txt."
    206 
    207 xml:
    208 	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
    209 	@echo
    210 	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
    211 
    212 pseudoxml:
    213 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
    214 	@echo
    215 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."