Mercurial > public > m209

annotate docs/Makefile @ 52:5b335e8af407

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Started roughing in some docs using Sphinx.
author Brian Neal <bgneal@gmail.com>
date Thu, 04 Jul 2013 22:41:30 -0500
parents 9c994664fdd6
children
rev   line source
bgneal@51 1 # Makefile for Sphinx documentation
bgneal@51 2 #
bgneal@51 3
bgneal@51 4 # You can set these variables from the command line.
bgneal@51 5 SPHINXOPTS =
bgneal@51 6 SPHINXBUILD = sphinx-build
bgneal@51 7 PAPER =
bgneal@51 8 BUILDDIR = _build
bgneal@51 9
bgneal@51 10 # User-friendly check for sphinx-build
bgneal@51 11 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
bgneal@51 12 $(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. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
bgneal@51 13 endif
bgneal@51 14
bgneal@51 15 # Internal variables.
bgneal@51 16 PAPEROPT_a4 = -D latex_paper_size=a4
bgneal@51 17 PAPEROPT_letter = -D latex_paper_size=letter
bgneal@51 18 ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
bgneal@51 19 # the i18n builder cannot share the environment and doctrees with the others
bgneal@51 20 I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
bgneal@51 21
bgneal@51 22 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
bgneal@51 23
bgneal@51 24 help:
bgneal@51 25 @echo "Please use \`make <target>' where <target> is one of"
bgneal@51 26 @echo " html to make standalone HTML files"
bgneal@51 27 @echo " dirhtml to make HTML files named index.html in directories"
bgneal@51 28 @echo " singlehtml to make a single large HTML file"
bgneal@51 29 @echo " pickle to make pickle files"
bgneal@51 30 @echo " json to make JSON files"
bgneal@51 31 @echo " htmlhelp to make HTML files and a HTML help project"
bgneal@51 32 @echo " qthelp to make HTML files and a qthelp project"
bgneal@51 33 @echo " devhelp to make HTML files and a Devhelp project"
bgneal@51 34 @echo " epub to make an epub"
bgneal@51 35 @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
bgneal@51 36 @echo " latexpdf to make LaTeX files and run them through pdflatex"
bgneal@51 37 @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
bgneal@51 38 @echo " text to make text files"
bgneal@51 39 @echo " man to make manual pages"
bgneal@51 40 @echo " texinfo to make Texinfo files"
bgneal@51 41 @echo " info to make Texinfo files and run them through makeinfo"
bgneal@51 42 @echo " gettext to make PO message catalogs"
bgneal@51 43 @echo " changes to make an overview of all changed/added/deprecated items"
bgneal@51 44 @echo " xml to make Docutils-native XML files"
bgneal@51 45 @echo " pseudoxml to make pseudoxml-XML files for display purposes"
bgneal@51 46 @echo " linkcheck to check all external links for integrity"
bgneal@51 47 @echo " doctest to run all doctests embedded in the documentation (if enabled)"
bgneal@51 48
bgneal@51 49 clean:
bgneal@51 50 rm -rf $(BUILDDIR)/*
bgneal@51 51
bgneal@51 52 html:
bgneal@51 53 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
bgneal@51 54 @echo
bgneal@51 55 @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
bgneal@51 56
bgneal@51 57 dirhtml:
bgneal@51 58 $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
bgneal@51 59 @echo
bgneal@51 60 @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
bgneal@51 61
bgneal@51 62 singlehtml:
bgneal@51 63 $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
bgneal@51 64 @echo
bgneal@51 65 @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
bgneal@51 66
bgneal@51 67 pickle:
bgneal@51 68 $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
bgneal@51 69 @echo
bgneal@51 70 @echo "Build finished; now you can process the pickle files."
bgneal@51 71
bgneal@51 72 json:
bgneal@51 73 $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
bgneal@51 74 @echo
bgneal@51 75 @echo "Build finished; now you can process the JSON files."
bgneal@51 76
bgneal@51 77 htmlhelp:
bgneal@51 78 $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
bgneal@51 79 @echo
bgneal@51 80 @echo "Build finished; now you can run HTML Help Workshop with the" \
bgneal@51 81 ".hhp project file in $(BUILDDIR)/htmlhelp."
bgneal@51 82
bgneal@51 83 qthelp:
bgneal@51 84 $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
bgneal@51 85 @echo
bgneal@51 86 @echo "Build finished; now you can run "qcollectiongenerator" with the" \
bgneal@51 87 ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
bgneal@51 88 @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/m209.qhcp"
bgneal@51 89 @echo "To view the help file:"
bgneal@51 90 @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/m209.qhc"
bgneal@51 91
bgneal@51 92 devhelp:
bgneal@51 93 $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
bgneal@51 94 @echo
bgneal@51 95 @echo "Build finished."
bgneal@51 96 @echo "To view the help file:"
bgneal@51 97 @echo "# mkdir -p $$HOME/.local/share/devhelp/m209"
bgneal@51 98 @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/m209"
bgneal@51 99 @echo "# devhelp"
bgneal@51 100
bgneal@51 101 epub:
bgneal@51 102 $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
bgneal@51 103 @echo
bgneal@51 104 @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
bgneal@51 105
bgneal@51 106 latex:
bgneal@51 107 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
bgneal@51 108 @echo
bgneal@51 109 @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
bgneal@51 110 @echo "Run \`make' in that directory to run these through (pdf)latex" \
bgneal@51 111 "(use \`make latexpdf' here to do that automatically)."
bgneal@51 112
bgneal@51 113 latexpdf:
bgneal@51 114 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
bgneal@51 115 @echo "Running LaTeX files through pdflatex..."
bgneal@51 116 $(MAKE) -C $(BUILDDIR)/latex all-pdf
bgneal@51 117 @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
bgneal@51 118
bgneal@51 119 latexpdfja:
bgneal@51 120 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
bgneal@51 121 @echo "Running LaTeX files through platex and dvipdfmx..."
bgneal@51 122 $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
bgneal@51 123 @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
bgneal@51 124
bgneal@51 125 text:
bgneal@51 126 $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
bgneal@51 127 @echo
bgneal@51 128 @echo "Build finished. The text files are in $(BUILDDIR)/text."
bgneal@51 129
bgneal@51 130 man:
bgneal@51 131 $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
bgneal@51 132 @echo
bgneal@51 133 @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
bgneal@51 134
bgneal@51 135 texinfo:
bgneal@51 136 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
bgneal@51 137 @echo
bgneal@51 138 @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
bgneal@51 139 @echo "Run \`make' in that directory to run these through makeinfo" \
bgneal@51 140 "(use \`make info' here to do that automatically)."
bgneal@51 141
bgneal@51 142 info:
bgneal@51 143 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
bgneal@51 144 @echo "Running Texinfo files through makeinfo..."
bgneal@51 145 make -C $(BUILDDIR)/texinfo info
bgneal@51 146 @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
bgneal@51 147
bgneal@51 148 gettext:
bgneal@51 149 $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
bgneal@51 150 @echo
bgneal@51 151 @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
bgneal@51 152
bgneal@51 153 changes:
bgneal@51 154 $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
bgneal@51 155 @echo
bgneal@51 156 @echo "The overview file is in $(BUILDDIR)/changes."
bgneal@51 157
bgneal@51 158 linkcheck:
bgneal@51 159 $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
bgneal@51 160 @echo
bgneal@51 161 @echo "Link check complete; look for any errors in the above output " \
bgneal@51 162 "or in $(BUILDDIR)/linkcheck/output.txt."
bgneal@51 163
bgneal@51 164 doctest:
bgneal@51 165 $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
bgneal@51 166 @echo "Testing of doctests in the sources finished, look at the " \
bgneal@51 167 "results in $(BUILDDIR)/doctest/output.txt."
bgneal@51 168
bgneal@51 169 xml:
bgneal@51 170 $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
bgneal@51 171 @echo
bgneal@51 172 @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
bgneal@51 173
bgneal@51 174 pseudoxml:
bgneal@51 175 $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
bgneal@51 176 @echo
bgneal@51 177 @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."