From d6a2003752ad2e00e6bdec1aebc47b697b9afca1 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Sun, 17 Oct 2010 16:30:15 +0200 Subject: [PATCH] Documentation update. Documentation will become the new Jinja2 website --- Makefile | 3 ++ docs/Makefile | 109 ++++++++++++++++++++++++++++++++++--------------- docs/index.rst | 39 +++++++++++++++--- docs/intro.rst | 19 --------- 4 files changed, 113 insertions(+), 57 deletions(-) diff --git a/Makefile b/Makefile index 60ca1d7..68b2199 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,7 @@ test: python setup.py test +website: + $(MAKE) -C docs dirhtml SPHINXOPTS=-Awebsite=1 + .PHONY: test diff --git a/docs/Makefile b/docs/Makefile index 5e24ec1..52d78d9 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,71 +5,114 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = +BUILDDIR = _build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html web pickle htmlhelp latex changes linkcheck +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp epub latex changes linkcheck doctest help: @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " changes to make an overview over all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" + @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 " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @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 " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: - -rm -rf _build/* + -rm -rf $(BUILDDIR)/* html: - mkdir -p _build/html _build/doctrees - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo - @echo "Build finished. The HTML pages are in _build/html." + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." pickle: - mkdir -p _build/pickle _build/doctrees - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo - @echo "Build finished; now you can process the pickle files" + @echo "Build finished; now you can process the pickle files." json: - mkdir -p _build/json _build/doctrees - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo - @echo "Build finished; now you can process the json files" - -web: pickle + @echo "Build finished; now you can process the JSON files." htmlhelp: - mkdir -p _build/htmlhelp _build/doctrees - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in _build/htmlhelp." + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Flask.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Flask.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) _build/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Flask" + @echo "# ln -s _build/devhelp $$HOME/.local/share/devhelp/Flask" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." latex: - mkdir -p _build/latex _build/doctrees - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo - @echo "Build finished; the LaTeX files are in _build/latex." + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ "run these through (pdf)latex." +latexpdf: latex + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex + @echo "Running LaTeX files through pdflatex..." + make -C _build/latex all-pdf + @echo "pdflatex finished; the PDF files are in _build/latex." + changes: - mkdir -p _build/changes _build/doctrees - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo - @echo "The overview file is in _build/changes." + @echo "The overview file is in $(BUILDDIR)/changes." linkcheck: - mkdir -p _build/linkcheck _build/doctrees - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ - "or in _build/linkcheck/output.txt." + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/index.rst b/docs/index.rst index 27bee23..6d050b4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,9 +1,32 @@ -Jinja2 Documentation -==================== +Welcome to Jinja2 +================= + +Jinja2 is a modern and designer friendly templating language for Python, +modelled after Django's templates. It is fast, widely used and secure +with the optional sandboxed template execution environment: + +.. sourcecode:: html+jinja -This is the documentation for the Jinja2 general purpose templating language. -Jinja2 is a library for Python 2.4 and onwards that is designed to be flexible, -fast and secure. + {% block title %}{% endblock %} + + +**Features:** + +- sandboxed execution +- powerful automatic HTML escaping system for XSS prevention +- template inheritance +- compiles down to the optimal python code just in time +- optional ahead of time template compilation +- easy to debug. Line numbers of exceptions directly point to + the correct line in the template. +- configurable syntax + +Jinja2 Documentation +-------------------- .. toctree:: :maxdepth: 2 @@ -17,6 +40,12 @@ fast and secure. switching tricks +Additional Information +---------------------- + +.. toctree:: + :maxdepth: 2 + faq changelog diff --git a/docs/intro.rst b/docs/intro.rst index 0800615..b08947d 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -10,25 +10,6 @@ Django, you should feel right at home with Jinja2. It's both designer and developer friendly by sticking to Python's principles and adding functionality useful for templating environments. -The key-features are... - -- ... **configurable syntax**. If you are generating LaTeX or other formats - with Jinja2 you can change the delimiters to something that integrates better - into the LaTeX markup. - -- ... **fast**. While performance is not the primarily target of Jinja2 it's - surprisingly fast. The overhead compared to regular Python code was reduced - to the very minimum. - -- ... **easy to debug**. Jinja2 integrates directly into the python traceback - system which allows you to debug Jinja2 templates with regular python - debugging helpers. - -- ... **secure**. It's possible to evaluate untrusted template code if the - optional sandbox is enabled. This allows Jinja2 to be used as templating - language for applications where users may modify the template design. - - Prerequisites ------------- -- 2.26.2