diff options
Diffstat (limited to 'test/doc/Makefile')
| -rw-r--r-- | test/doc/Makefile | 243 |
1 files changed, 243 insertions, 0 deletions
diff --git a/test/doc/Makefile b/test/doc/Makefile new file mode 100644 index 00000000..ff96b5fd --- /dev/null +++ b/test/doc/Makefile @@ -0,0 +1,243 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SRC_DOC_DIR = $(WS_ROOT)/test/doc +SPHINXBUILD = sphinx-build +PAPER = +BUILD_DOC_ROOT = $(BR)/test-doc +BUILD_DOC_DIR = $(BUILD_DOC_ROOT)/build +API_DOC_GEN_DIR = $(BUILD_DOC_ROOT)/apidoc + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILD_DOC_DIR)/.sphinx-cache $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(API_DOC_GEN_DIR) -c $(SRC_DOC_DIR) +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +IN_VENV:=$(shell if pip -V | grep "virtualenv" 2>&1 > /dev/null; then echo 1; else echo 0; fi) + +.PHONY: verify-virtualenv +verify-virtualenv: +ifeq ($(IN_VENV),0) + $(error "Not running inside virtualenv (are you running 'make test-doc' from root?)") +endif + +.PHONY: regen-api-doc +regen-api-doc: verify-virtualenv + @mkdir -p $(API_DOC_GEN_DIR) + @cp $(SRC_DOC_DIR)/index.rst $(API_DOC_GEN_DIR) + @cp $(SRC_DOC_DIR)/indices.rst $(API_DOC_GEN_DIR) + @cp $(SRC_DOC_DIR)/overview.rst $(API_DOC_GEN_DIR) + sphinx-apidoc -o $(API_DOC_GEN_DIR) -H "Module documentation" .. + +.PHONY: help +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " epub3 to make an epub3" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: wipe +wipe: + rm -rf $(BUILD_DOC_ROOT) + +.PHONY: html +html: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILD_DOC_DIR)/html." + +.PHONY: dirhtml +dirhtml: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILD_DOC_DIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILD_DOC_DIR)/singlehtml." + +.PHONY: pickle +pickle: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILD_DOC_DIR)/htmlhelp." + +.PHONY: qthelp +qthelp: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILD_DOC_DIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILD_DOC_DIR)/qthelp/VPPtestframework.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILD_DOC_DIR)/qthelp/VPPtestframework.qhc" + +.PHONY: applehelp +applehelp: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILD_DOC_DIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/VPPtestframework" + @echo "# ln -s $(BUILD_DOC_DIR)/devhelp $$HOME/.local/share/devhelp/VPPtestframework" + @echo "# devhelp" + +.PHONY: epub +epub: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILD_DOC_DIR)/epub." + +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILD_DOC_DIR)/epub3." + +.PHONY: latex +latex: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILD_DOC_DIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILD_DOC_DIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILD_DOC_DIR)/latex." + +.PHONY: latexpdfja +latexpdfja: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILD_DOC_DIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILD_DOC_DIR)/latex." + +.PHONY: text +text: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/text + @echo + @echo "Build finished. The text files are in $(BUILD_DOC_DIR)/text." + +.PHONY: man +man: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILD_DOC_DIR)/man." + +.PHONY: texinfo +texinfo: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILD_DOC_DIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILD_DOC_DIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILD_DOC_DIR)/texinfo." + +.PHONY: gettext +gettext: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILD_DOC_DIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILD_DOC_DIR)/locale." + +.PHONY: changes +changes: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/changes + @echo + @echo "The overview file is in $(BUILD_DOC_DIR)/changes." + +.PHONY: linkcheck +linkcheck: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILD_DOC_DIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILD_DOC_DIR)/doctest/output.txt." + +.PHONY: coverage +coverage: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILD_DOC_DIR)/coverage/python.txt." + +.PHONY: xml +xml: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILD_DOC_DIR)/xml." + +.PHONY: pseudoxml +pseudoxml: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILD_DOC_DIR)/pseudoxml." + +.PHONY: dummy +dummy: regen-api-doc verify-virtualenv + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." |