From 229512391b67ea3f87366e0c97d2bc11232c8856 Mon Sep 17 00:00:00 2001 From: Iacopo Spalletti Date: Tue, 9 Feb 2016 01:09:31 +0100 Subject: [PATCH 1/8] Add documentatio support --- .gitignore | 1 + cms_helper.py | 5 + docs/Makefile | 177 ++++++++++++++++++++++++++++++++ docs/conf.py | 274 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 9 ++ docs/make.bat | 242 +++++++++++++++++++++++++++++++++++++++++++ tox.ini | 10 ++ 7 files changed, 718 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat diff --git a/.gitignore b/.gitignore index 6320419..9114b11 100644 --- a/.gitignore +++ b/.gitignore @@ -7,4 +7,5 @@ MANIFEST .idea .coverage *.egg-info +docs/_build *.iml diff --git a/cms_helper.py b/cms_helper.py index 55ff62d..97c8fe7 100755 --- a/cms_helper.py +++ b/cms_helper.py @@ -26,5 +26,10 @@ def run(): runner.run('meta') +def setup(): + import sys + from djangocms_helper import runner + runner.setup('meta', sys.modules[__name__]) + if __name__ == '__main__': run() diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..84d75d7 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(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/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where 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 " 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 " 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)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @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: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".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/djangoCMSHelper.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/djangoCMSHelper.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/djangoCMSHelper" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/djangoCMSHelper" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "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." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..601fa73 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,274 @@ +# -*- coding: utf-8 -*- +# +# Django App Helper documentation build configuration file, created by +# sphinx-quickstart on Thu Dec 18 19:02:40 2014. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('../tests')) + +import cms_helper +import meta +cms_helper.setup() + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + #'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Django App Helper' +copyright = u'2014, Iacopo Spalletti' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = meta.__version__ +# The full version, including alpha/beta/rc tags. +release = meta.__version__ + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +import sphinx_rtd_theme + +html_theme = "sphinx_rtd_theme" + +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'djangoCMSHelperdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'djangoCMSHelper.tex', u'Django App Helper Documentation', + u'Iacopo Spalletti', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'djangocmshelper', u'Django App Helper Documentation', + [u'Iacopo Spalletti'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'djangoCMSHelper', u'Django App Helper Documentation', + u'Iacopo Spalletti', 'djangoCMSHelper', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..b1b3f7f --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,9 @@ +########### +django meta +########### + +A pluggable app allows Django developers to quickly add meta tags and +OpenGraph_, Twitter, and Google Plus properties to their HTML responses. + + +.. _OpenGraph: http://opengraphprotocol.org/ diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..811ccf5 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,242 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ 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. 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. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over 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 + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\djangoCMSHelper.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\djangoCMSHelper.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end diff --git a/tox.ini b/tox.ini index f374f8b..ee5be76 100644 --- a/tox.ini +++ b/tox.ini @@ -23,3 +23,13 @@ skip_install = true deps = isort commands = isort -c -rc -df meta meta_mixin tests skip_install = true + +[testenv:docs] +deps = + sphinx + sphinx-rtd-theme + -rrequirements-test.txt +changedir=docs +skip_install = true +commands= + sphinx-build -W -b html -d {envtmpdir}/doctrees . {toxinidir}/docs/_build/html From 4ad909ffa781540317794a41f3400b4fcc80116e Mon Sep 17 00:00:00 2001 From: Iacopo Spalletti Date: Tue, 9 Feb 2016 01:28:23 +0100 Subject: [PATCH 2/8] Docs skeleton --- README.rst | 126 +----------------------------------------- docs/contributing.rst | 1 + docs/development.rst | 19 +++++++ docs/history.rst | 1 + docs/index.rst | 27 +++++++++ docs/models.rst | 6 ++ docs/rendering.rst | 22 ++++++++ docs/settings.rst | 117 +++++++++++++++++++++++++++++++++++++++ docs/views.rst | 6 ++ 9 files changed, 200 insertions(+), 125 deletions(-) create mode 100644 docs/contributing.rst create mode 100644 docs/development.rst create mode 100644 docs/history.rst create mode 100644 docs/models.rst create mode 100644 docs/rendering.rst create mode 100644 docs/settings.rst create mode 100644 docs/views.rst diff --git a/README.rst b/README.rst index 51f2089..2d86da9 100644 --- a/README.rst +++ b/README.rst @@ -369,123 +369,6 @@ like so:: There are two more methods that you can overload in your view classes, and those are ``get_domain`` and ``get_protocol``. -Rendering meta tags -=================== - -To render the meta tags, simply add the ``meta`` dictionary/object to the -template context, and add this inside the ```` tags:: - - {% include 'meta.html' %} - -The partial template will not output anything if the context dictionary does -not contain a ``meta`` object, so you can safely include it in your base -template. - -Additionally, if you want to use facebook or a custom namespace, you should include -them in the tag, as follow:: - - {% load meta %} - - -This will take care of rendering OpenGraph namespaces in the ````. - -Configuration -============= - -django-meta has a few configuration options that allow you to customize it. Two -of them are required. Those are ``META_SITE_PROTOCOL`` and -``META_SITE_DOMAIN``. By default, if they are unset, an -``ImproperlyConfigured`` exception will raised when dealing with ``url`` and -``image`` properties. You can either set them, or overload the ``Meta`` class' -``get_domain`` and ``get_protocol`` methods (see `Meta objects`_ section). - -META_SITE_PROTOCOL ------------------- - -Defines the protocol used on your site. This should be set to either ``'http'`` -or ``'https'``. Default is ``None``. - -META_SITE_DOMAIN ----------------- - -Domain of your site. The ``Meta`` objects can also be made to use the Django's -Sites framework as well (see `Meta objects`_ and META_USE_SITES_ sections). -Default is ``None``. - -META_SITE_TYPE --------------- - -The default ``og:type`` property to use site-wide. You do not need to set this -if you do not intend to use the OpenGraph properties. Default is ``None``. - -META_SITE_NAME --------------- - -The site name to use in ``og:site_name`` property. Althoug this can be -set per view, we recommend you set it globally. Defalt is ``None``. - -META_INCLUDE_KEYWORDS ---------------------- - -Iterable of extra keywords to include in every view. These keywords are -appended to whatever keywords you specify for the view, but are not used at all -if no keywords are specified for the view. See META_DEFAULT_KEYWORDS_ if you -wish to specify keywords to be used when no keywords are supplied. Default is -``[]``. - -META_DEFAULT_KEYWORDS ---------------------- - -Iterable of default keywords to use when no keywords are specified for the -view. These keywords are not included if you specify keywords for the view. If -you need keywords that will always be present, regardless of whether you've -specified any other keywords for the view or not, you need to combine this -setting with META_INCLUDE_KEYWORDS_ setting. Default is ``[]``. - -META_IMAGE_URL --------------- - -This setting is used as the base URL for all image assets that you intend to -use as ``og:image`` property in your views. This is django-meta's counterpart -of the Django's ``STATIC_URL`` setting. In fact, Django's ``STATIC_URL`` -setting is a fallback if you do not specify this setting, so make sure either -one is configured. Default is to use the ``STATIC_URL`` setting. - -Note that you must add the trailing slash when specifying the URL. Even if you -do not intend to use the ``og:image`` property, you need to define either this -setting or the ``STATIC_URL`` setting or an attribute error will be raised. - -META_USE_OG_PROPERTIES ----------------------- - -This setting tells django-meta whether to render the OpenGraph properties. -Default is ``False``. - -META_USE_TWITTER_PROPERTIES ---------------------------- - -This setting tells django-meta whether to render the Twitter properties. -Default is ``False``. - -META_USE_GOOGLEPLUS_PROPERTIES ------------------------------- - -This setting tells django-meta whether to render the Google properties. -Default is ``False``. - -META_USE_TITLE_TAG ------------------- - -This setting tells django-meta whether to render the ```` tag. -Default is ``False``. - -META_USE_SITES --------------- - -This setting tells django-meta to derive the site's domain using the Django's -sites contrib app. If you enable this setting, the META_SITE_DOMAIN_ is not -used at all. Default is ``False``. - Authors and Contributors ======================== @@ -493,11 +376,7 @@ Authors and Contributors Current maintainer: `Iacopo Spalletti`_ -We thank the contributors to this project: - -+ leifdenby_ -+ m-vdb_ -+ DmitryFillo_ +See ``AUTHORS`` file for the complete list of contributors Reporting bugs ============== @@ -507,9 +386,6 @@ Please report all bugs to our Github `issue tracker`_. .. _OpenGraph: http://opengraphprotocol.org/ .. _issue tracker: https://github.com/nephila/django-meta/issues/ .. _github: https://github.com/nephila/django-meta/ -.. _leifdenby: https://bitbucket.org/leifdenby -.. _m-vdb: https://github.com/m-vdb -.. _DmitryFillo: https://github.com/DmitryFillo .. _Iacopo Spalletti: https://github.com/yakky .. _Branko Vukelic: https://bitbucket.org/monwara diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..3bdd7dc --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1 @@ +.. include:: ../CONTRIBUTING.rst \ No newline at end of file diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 index 0000000..80318d5 --- /dev/null +++ b/docs/development.rst @@ -0,0 +1,19 @@ +####################### +Development & community +####################### + +django meta is an open-source project. + +You don't need to be an expert developer to make a valuable contribution - all you need is a little +knowledge, and a willingness to follow the contribution guidelines. + +******* +Nephila +******* + +django meta is maintained by Iacopo Spalletti at `Nephila `_ +and is released under a GNU GENERAL PUBLIC LICENSE. + +Nephila is an active supporter of django CMS and its community. django meta is intended to +help make it easier for developers in the Django ecosystem to work effectively and create +high quality applications. diff --git a/docs/history.rst b/docs/history.rst new file mode 100644 index 0000000..bec23d8 --- /dev/null +++ b/docs/history.rst @@ -0,0 +1 @@ +.. include:: ../HISTORY.rst \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index b1b3f7f..db32179 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,5 +5,32 @@ django meta A pluggable app allows Django developers to quickly add meta tags and OpenGraph_, Twitter, and Google Plus properties to their HTML responses. +Usage +----- + +django meta has two different operating mode: + + * :ref:`models` + * :ref:`views` + + + +.. toctree:: + :maxdepth: 2 + + models + views + settings + rendering + development + contributing + history + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` .. _OpenGraph: http://opengraphprotocol.org/ diff --git a/docs/models.rst b/docs/models.rst new file mode 100644 index 0000000..c73fece --- /dev/null +++ b/docs/models.rst @@ -0,0 +1,6 @@ +.. _models: + +************* +Model support +************* + diff --git a/docs/rendering.rst b/docs/rendering.rst new file mode 100644 index 0000000..679b6a6 --- /dev/null +++ b/docs/rendering.rst @@ -0,0 +1,22 @@ +.. _rendering: + +******************* +Rendering meta tags +******************* + +To render the meta tags, simply add the ``meta`` dictionary/object to the +template context, and add this inside the ```` tags:: + + {% include 'meta/meta.html' %} + +The partial template will not output anything if the context dictionary does +not contain a ``meta`` object, so you can safely include it in your base +template. + +Additionally, if you want to use facebook or a custom namespace, you should include +them in the tag, as follow:: + + {% load meta %} + + +This will take care of rendering OpenGraph namespaces in the ````. diff --git a/docs/settings.rst b/docs/settings.rst new file mode 100644 index 0000000..6229d9a --- /dev/null +++ b/docs/settings.rst @@ -0,0 +1,117 @@ +.. _settings: + +******** +Settings +******** + + +django-meta has a few configuration options that allow you to customize it. Two +of them are required. Those are ``META_SITE_PROTOCOL`` and +``META_SITE_DOMAIN``. By default, if they are unset, an +``ImproperlyConfigured`` exception will raised when dealing with ``url`` and +``image`` properties. You can either set them, or overload the ``Meta`` class' +``get_domain`` and ``get_protocol`` methods (see `Meta objects`_ section). + +META_SITE_PROTOCOL +------------------ + +Defines the protocol used on your site. This should be set to either ``'http'`` +or ``'https'``. Default is ``None``. + +META_SITE_DOMAIN +---------------- + +Domain of your site. The ``Meta`` objects can also be made to use the Django's +Sites framework as well (see `Meta objects`_ and META_USE_SITES_ sections). +Default is ``None``. + +META_SITE_TYPE +-------------- + +The default ``og:type`` property to use site-wide. You do not need to set this +if you do not intend to use the OpenGraph properties. Default is ``None``. + +META_SITE_NAME +-------------- + +The site name to use in ``og:site_name`` property. Althoug this can be +set per view, we recommend you set it globally. Defalt is ``None``. + +META_INCLUDE_KEYWORDS +--------------------- + +Iterable of extra keywords to include in every view. These keywords are +appended to whatever keywords you specify for the view, but are not used at all +if no keywords are specified for the view. See META_DEFAULT_KEYWORDS_ if you +wish to specify keywords to be used when no keywords are supplied. Default is +``[]``. + +META_DEFAULT_KEYWORDS +--------------------- + +Iterable of default keywords to use when no keywords are specified for the +view. These keywords are not included if you specify keywords for the view. If +you need keywords that will always be present, regardless of whether you've +specified any other keywords for the view or not, you need to combine this +setting with META_INCLUDE_KEYWORDS_ setting. Default is ``[]``. + +META_IMAGE_URL +-------------- + +This setting is used as the base URL for all image assets that you intend to +use as ``og:image`` property in your views. This is django-meta's counterpart +of the Django's ``STATIC_URL`` setting. In fact, Django's ``STATIC_URL`` +setting is a fallback if you do not specify this setting, so make sure either +one is configured. Default is to use the ``STATIC_URL`` setting. + +Note that you must add the trailing slash when specifying the URL. Even if you +do not intend to use the ``og:image`` property, you need to define either this +setting or the ``STATIC_URL`` setting or an attribute error will be raised. + +META_USE_OG_PROPERTIES +---------------------- + +This setting tells django-meta whether to render the OpenGraph properties. +Default is ``False``. + +META_USE_TWITTER_PROPERTIES +--------------------------- + +This setting tells django-meta whether to render the Twitter properties. +Default is ``False``. + +META_USE_GOOGLEPLUS_PROPERTIES +------------------------------ + +This setting tells django-meta whether to render the Google properties. +Default is ``False``. + +META_USE_TITLE_TAG +------------------ + +This setting tells django-meta whether to render the ```` tag. +Default is ``False``. + +META_USE_SITES +-------------- + +This setting tells django-meta to derive the site's domain using the Django's +sites contrib app. If you enable this setting, the META_SITE_DOMAIN_ is not +used at all. Default is ``False``. + + +Other settings +-------------- + +* image: ``META_DEFAULT_IMAGE`` (must be an absolute URL) +* object_type: ``META_SITE_TYPE`` (default: first ``META_OBJECT_TYPES``) +* og_type: ``META_FB_TYPE`` (default: first ``META_FB_TYPES``) +* og_app_id: ``META_FB_APPID`` (default: blank) +* og_profile_id: ``META_FB_PROFILE_ID`` (default: blank) +* og_publisher: ``META_FB_PUBLISHER`` (default: blank) +* og_author_url: ``META_FB_AUTHOR_URL`` (default: blank) +* twitter_type: ``META_TWITTER_TYPE`` (default: first ``META_TWITTER_TYPES``) +* twitter_site: ``META_TWITTER_SITE`` (default: blank) +* twitter_author: ``META_TWITTER_AUTHOR`` (default: blank) +* gplus_type: ``META_GPLUS_TYPE`` (default: first ``META_GPLUS_TYPES``) +* gplus_author: ``META_GPLUS_AUTHOR`` (default: blank) diff --git a/docs/views.rst b/docs/views.rst new file mode 100644 index 0000000..5802690 --- /dev/null +++ b/docs/views.rst @@ -0,0 +1,6 @@ +.. _views: + +************ +View support +************ + From 59e63be1ecdd9692a862425792756099a1fb937f Mon Sep 17 00:00:00 2001 From: Marco Federighi Date: Mon, 29 Feb 2016 10:58:03 +0100 Subject: [PATCH 3/8] Move view doc in the dev doc section --- README.rst | 289 ------------------------------------------------- docs/views.rst | 289 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 289 insertions(+), 289 deletions(-) diff --git a/README.rst b/README.rst index 2d86da9..fdb1c2d 100644 --- a/README.rst +++ b/README.rst @@ -79,295 +79,6 @@ Basic concept ``django-meta`` provides a **view-method** and **model-method** interface to provide -Using the view --------------- - -You render the meta tags by including a ``meta.html`` partial template in your -view templates. This template will only render meta tags if it can find a -``meta`` object in the context, so you can safely include it in your base -template to have it render on all your pages. - -The ``meta.html`` template expects to find a dict or object called ``meta`` in -the template context. In that dict or object, it will expect to find any of the -following keys/attributes: - -+ use_og -+ use_twitter -+ use_facebook -+ use_googleplus -+ use_title_tag -+ title -+ description -+ keywords -+ url -+ image -+ object_type -+ site_name -+ twitter_site -+ twitter_creator -+ twitter_card -+ facebook_app_id -+ locale -+ extra_props -+ extra_custom_props - -In all cases, if the key is omitted, the matching metadata/property is not -rendered. - -use_og ------- - -This key contains a boolean value, and instructs the template to render the -OpenGraph_ properties. These are usually used by FaceBook to get more -information about your site's pages. - -use_twitter ------------ - -This key contains a boolean value, and instructs the template to render the -Twitter properties. These are usually used by Twitter to get more -information about your site's pages. - -use_facebook ------------- - -This key contains a boolean value, and instructs the template to render the -Facebook properties. These are usually used by Facebook to get more -information about your site's pages. - -use_googleplus --------------- - -This key contains a boolean value, and instructs the template to render the -Google+. These are usually used by Google to get more information about your -site's pages. - -use_title_tag -------------- - -This key contains a boolean value, and instructs the template to render the -```` tag. In the simple case, you use ```` tag -in the templates where you can override it, but if you want to generate it -dynamically in the views, you can set this property to ``True``. - -title ------ - -This key is used in the ``og:title`` OpenGraph property if ``use_og`` is -``True``, ``twitter:title`` if ``use_twitter`` is ``True``, -``itemprop="title"`` if ``use_googleplus`` is ``True`` or ```` tag -if ``use_title_tag`` is ``True``. - -description ------------ - -This key is used to render the ``description`` meta tag as well as the -``og:description`` and ``twitter:description`` property. - -keywords --------- - -This key should be an iterable containing the keywords for the page. It is used -to render the ``keywords`` meta tag. - -url ---- - -This key should be the *full* URL of the page. It is used to render the -``og:url``, ``twitter:url``, ``itemprop=url`` property. - -image ------ - -This key should be the *full* URL of an image to be used with the ``og:image``, -``twitter:image``, ``itemprop=mage`` property. - -object_type ------------ - -This key is used to render the ``og:type`` property. - -site_name ---------- - -This key is used to render the ``og:site_name`` property. - -twitter_site ------------- - -This key is used to render the ``twitter:site`` property. - -twitter_creator ---------------- - -This key is used to render the ``twitter:creator`` property. - -twitter_card ------------- - -This key is used to render the ``twitter:card`` property. - -facebook_app_id ---------------- - -This key is used to render the ``fb:app_id`` property. - -locale ------- - -This key is used to render the ``og:locale`` property. - -extra_props ------------ - -A dictionary of extra optional properties:: - - { - 'foo': 'bar', - 'key': 'value' - } - - ... - - - - -extra_custom_props ------------------- - -A list of tuples for rendering custom extra properties:: - - [ - ('key', 'foo', 'bar') - ('property', 'name', 'value') - ] - - ... - - - - -Meta objects -============ - -The core of django-meta is the ``Meta`` class. Although you can prepare the -metadata for the template yourself, this class can make things somewhat -easier. - -To set up a meta object for use in templates, simply instantiate it with the -properties you want to use:: - - from meta.views import Meta - - meta = Meta( - title="Sam's awesome ponies", - description='Awesome page about ponies', - keywords=['pony', 'ponies', 'awesome'], - extra_props = { - 'viewport': 'width=device-width, initial-scale=1.0, minimum-scale=1.0' - } - 'extra_custom_props': [ - ('http-equiv', 'Content-Type', 'text/html; charset=UTF-8'), - ] - ) - -When the time comes to render the template, simply include the instance as -``'meta'`` context variable. - -The ``Meta`` instances have the same properties as the keys listed in the -`Basic concept`_ section. For convenience, some of the properties are 'smart', -and will modify values you set. These properties are: - -+ keywords -+ url -+ image - -For brevity, we will only discuss those here. - -Meta.keywords -------------- - -When you assign keywords either via the constructor, or by assigning an -iterable to the ``keywords`` property, it will be cleaned up of all duplicates -and returned as a ``set``. If you have specified the META_INCLUDE_KEYWORDS_, -the resulting set will also include them. If you omit this argument when -instantiating the object, or if you assign ``None`` to the ``keywords`` -property, keywords defined by META_DEFAULT_KEYWORDS_ setting will be used -instead. - -Meta.url --------- - -Setting the url behaves differently depending on whether you are passsing a -path or a full URL. If your URL starts with ``'http'``, it will be used -verbatim (not that the actual validity of the url is not checked so -``'httpfoo'`` will be considered a valid URL). If you use an absolute or -relative path, domain and protocol parts would be prepended to the URL. Here's -an example:: - - m = Meta(url='/foo/bar') - m.url # returns 'http://example.com/foo/bar' - -The actual protocol and domain are dependent on the META_SITE_PROTOCOL_ and -META_SITE_DOMAIN_ settings. If you wish to use the Django's sites contrib app -to calculate the domain, you can either set the META_USE_SITES_ setting to -``True``, or pass the ``use_sites`` argument to the constructor:: - - m = Meta(url='/foo/bar', use_sites=True) - -Note that using the sites app will trigger database queries and/or cache hits, -and it is therefore disabled by default. - -Meta.image ----------- - -The ``image`` property behaves the same way as ``url`` property with one -notable difference. This property treats absolute and relative paths -differently. It will place relative paths under the META_IMAGE_URL_. - -View mixin -========== - -As a convenience to those who embrace the Django's class-based views, -django-meta includes a mixin that can be used with your views. Using the mixin -is very simple:: - - from django.views.generic import View - - from meta.views import MetadataMixin - - - class MyView(MetadataMixin, View): - title = 'Some page' - description = 'This is an awesome page' - image = 'img/some_page_thumb.gif' - url = 'some/page/' - - .... - - -The mixin sports all properties listed in the `Basic concept`_ section with a -few additional bells and whistles that make working with them easier. The mixin -will return an instance of the ``Meta`` class (see `Meta objects`_) as ``meta`` -context variable. This is, in turn, used in the partial template to render the -meta tags (see `Rendering meta tags`_). - -Each of the properties on the mixin can be calculated dynamically by using the -``MetadataMixin.get_meta_PROPERTYNAME`` methods, where ``PROPERTYNAME`` is the -name of the property you wish the calculate at runtime. Each method will -receive a ``context`` keyword argument containig the request context. - -For example, to calculate the description dynamically, you may use the mixin -like so:: - - class MyView(MetadataMixin, SingleObjectMixin, View): - ... - - def get_meta_description(self, context): - return self.get_object().description - -There are two more methods that you can overload in your view classes, and -those are ``get_domain`` and ``get_protocol``. Authors and Contributors ======================== diff --git a/docs/views.rst b/docs/views.rst index 5802690..70f30bc 100644 --- a/docs/views.rst +++ b/docs/views.rst @@ -4,3 +4,292 @@ View support ************ +Using the view +-------------- + +You render the meta tags by including a ``meta.html`` partial template in your +view templates. This template will only render meta tags if it can find a +``meta`` object in the context, so you can safely include it in your base +template to have it render on all your pages. + +The ``meta.html`` template expects to find a dict or object called ``meta`` in +the template context. In that dict or object, it will expect to find any of the +following keys/attributes: + ++ use_og ++ use_twitter ++ use_facebook ++ use_googleplus ++ use_title_tag ++ title ++ description ++ keywords ++ url ++ image ++ object_type ++ site_name ++ twitter_site ++ twitter_creator ++ twitter_card ++ facebook_app_id ++ locale ++ extra_props ++ extra_custom_props + +In all cases, if the key is omitted, the matching metadata/property is not +rendered. + +use_og +------ + +This key contains a boolean value, and instructs the template to render the +OpenGraph_ properties. These are usually used by FaceBook to get more +information about your site's pages. + +use_twitter +----------- + +This key contains a boolean value, and instructs the template to render the +Twitter properties. These are usually used by Twitter to get more +information about your site's pages. + +use_facebook +------------ + +This key contains a boolean value, and instructs the template to render the +Facebook properties. These are usually used by Facebook to get more +information about your site's pages. + +use_googleplus +-------------- + +This key contains a boolean value, and instructs the template to render the +Google+. These are usually used by Google to get more information about your +site's pages. + +use_title_tag +------------- + +This key contains a boolean value, and instructs the template to render the +```` tag. In the simple case, you use ```` tag +in the templates where you can override it, but if you want to generate it +dynamically in the views, you can set this property to ``True``. + +title +----- + +This key is used in the ``og:title`` OpenGraph property if ``use_og`` is +``True``, ``twitter:title`` if ``use_twitter`` is ``True``, +``itemprop="title"`` if ``use_googleplus`` is ``True`` or ```` tag +if ``use_title_tag`` is ``True``. + +description +----------- + +This key is used to render the ``description`` meta tag as well as the +``og:description`` and ``twitter:description`` property. + +keywords +-------- + +This key should be an iterable containing the keywords for the page. It is used +to render the ``keywords`` meta tag. + +url +--- + +This key should be the *full* URL of the page. It is used to render the +``og:url``, ``twitter:url``, ``itemprop=url`` property. + +image +----- + +This key should be the *full* URL of an image to be used with the ``og:image``, +``twitter:image``, ``itemprop=mage`` property. + +object_type +----------- + +This key is used to render the ``og:type`` property. + +site_name +--------- + +This key is used to render the ``og:site_name`` property. + +twitter_site +------------ + +This key is used to render the ``twitter:site`` property. + +twitter_creator +--------------- + +This key is used to render the ``twitter:creator`` property. + +twitter_card +------------ + +This key is used to render the ``twitter:card`` property. + +facebook_app_id +--------------- + +This key is used to render the ``fb:app_id`` property. + +locale +------ + +This key is used to render the ``og:locale`` property. + +extra_props +----------- + +A dictionary of extra optional properties:: + + { + 'foo': 'bar', + 'key': 'value' + } + + ... + + + + +extra_custom_props +------------------ + +A list of tuples for rendering custom extra properties:: + + [ + ('key', 'foo', 'bar') + ('property', 'name', 'value') + ] + + ... + + + + +Meta objects +============ + +The core of django-meta is the ``Meta`` class. Although you can prepare the +metadata for the template yourself, this class can make things somewhat +easier. + +To set up a meta object for use in templates, simply instantiate it with the +properties you want to use:: + + from meta.views import Meta + + meta = Meta( + title="Sam's awesome ponies", + description='Awesome page about ponies', + keywords=['pony', 'ponies', 'awesome'], + extra_props = { + 'viewport': 'width=device-width, initial-scale=1.0, minimum-scale=1.0' + } + 'extra_custom_props': [ + ('http-equiv', 'Content-Type', 'text/html; charset=UTF-8'), + ] + ) + +When the time comes to render the template, simply include the instance as +``'meta'`` context variable. + +The ``Meta`` instances have the same properties as the keys listed in the +`Basic concept`_ section. For convenience, some of the properties are 'smart', +and will modify values you set. These properties are: + ++ keywords ++ url ++ image + +For brevity, we will only discuss those here. + +Meta.keywords +------------- + +When you assign keywords either via the constructor, or by assigning an +iterable to the ``keywords`` property, it will be cleaned up of all duplicates +and returned as a ``set``. If you have specified the META_INCLUDE_KEYWORDS_, +the resulting set will also include them. If you omit this argument when +instantiating the object, or if you assign ``None`` to the ``keywords`` +property, keywords defined by META_DEFAULT_KEYWORDS_ setting will be used +instead. + +Meta.url +-------- + +Setting the url behaves differently depending on whether you are passsing a +path or a full URL. If your URL starts with ``'http'``, it will be used +verbatim (not that the actual validity of the url is not checked so +``'httpfoo'`` will be considered a valid URL). If you use an absolute or +relative path, domain and protocol parts would be prepended to the URL. Here's +an example:: + + m = Meta(url='/foo/bar') + m.url # returns 'http://example.com/foo/bar' + +The actual protocol and domain are dependent on the META_SITE_PROTOCOL_ and +META_SITE_DOMAIN_ settings. If you wish to use the Django's sites contrib app +to calculate the domain, you can either set the META_USE_SITES_ setting to +``True``, or pass the ``use_sites`` argument to the constructor:: + + m = Meta(url='/foo/bar', use_sites=True) + +Note that using the sites app will trigger database queries and/or cache hits, +and it is therefore disabled by default. + +Meta.image +---------- + +The ``image`` property behaves the same way as ``url`` property with one +notable difference. This property treats absolute and relative paths +differently. It will place relative paths under the META_IMAGE_URL_. + +View mixin +========== + +As a convenience to those who embrace the Django's class-based views, +django-meta includes a mixin that can be used with your views. Using the mixin +is very simple:: + + from django.views.generic import View + + from meta.views import MetadataMixin + + + class MyView(MetadataMixin, View): + title = 'Some page' + description = 'This is an awesome page' + image = 'img/some_page_thumb.gif' + url = 'some/page/' + + .... + + +The mixin sports all properties listed in the `Basic concept`_ section with a +few additional bells and whistles that make working with them easier. The mixin +will return an instance of the ``Meta`` class (see `Meta objects`_) as ``meta`` +context variable. This is, in turn, used in the partial template to render the +meta tags (see `Rendering meta tags`_). + +Each of the properties on the mixin can be calculated dynamically by using the +``MetadataMixin.get_meta_PROPERTYNAME`` methods, where ``PROPERTYNAME`` is the +name of the property you wish the calculate at runtime. Each method will +receive a ``context`` keyword argument containig the request context. + +For example, to calculate the description dynamically, you may use the mixin +like so:: + + class MyView(MetadataMixin, SingleObjectMixin, View): + ... + + def get_meta_description(self, context): + return self.get_object().description + +There are two more methods that you can overload in your view classes, and +those are ``get_domain`` and ``get_protocol``. \ No newline at end of file From 783a08b47cba89c261e026a2728c53964123b243 Mon Sep 17 00:00:00 2001 From: Marco Federighi Date: Mon, 29 Feb 2016 11:23:26 +0100 Subject: [PATCH 4/8] Update README --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index fdb1c2d..66f9d41 100644 --- a/README.rst +++ b/README.rst @@ -77,7 +77,7 @@ Python Basic concept ============= -``django-meta`` provides a **view-method** and **model-method** interface to provide +``django-meta`` provides a **view-method** and **model-method** interface to provide and handle meta informations Authors and Contributors From da9d068e6a873882abd5a07740b1f83c0c2c891a Mon Sep 17 00:00:00 2001 From: Marco Federighi Date: Mon, 29 Feb 2016 11:38:50 +0100 Subject: [PATCH 5/8] Add model doc --- docs/models.rst | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/models.rst b/docs/models.rst index c73fece..7856ac4 100644 --- a/docs/models.rst +++ b/docs/models.rst @@ -4,3 +4,50 @@ Model support ************* +Concepts +-------- + +**django-meta* provides a mixin to handle metadata in your models. + +Actual data are evaluated at runtime pulling values from model attributes and +methods. + +To use it, defines a ``_metadata`` attribute as a dictionary of tag/value pairs; + +* **tag** is the name of the metatag as used by ``meta.html`` template +* **value** is a string that is evaluated in the following order: + + * model method name called with the meta attribute as argument + * model method name called with no arguments + * model attribute name (evaluated at runtime) + * string literal (if none of the above exists) + +If **value** is ``False`` or it is evaluated as ``False`` at runtime the tag is skipped. + +To use this mixin you must invoke ``as_meta()`` on the model instance +for example in the get_context_data(). + +Request ++++++++ + +``as_meta()`` accepts the ``request`` object that is saved locally and is available to methods by +using the ``get_request`` method. + + +Public interface +++++++++++++++++ + +``ModelMeta.get_meta(request=None)``: returns the metadata attributes definition. Tipically these +are set in ``_metadata`` attribute in the model; + +``ModelMeta.as_meta(request=None)``: returns the meta representation of the object suitable for +use in the template; + +``ModelMeta.get_request()``: returns the ``request`` object, if given as argument to ``as_meta``; + +``ModelMeta.get_author()``: returns the author object for the current instance. Default +implementation does not return a valid object, this **must** be overidden in the application +according to what is an author in the application domain; + +``ModelMeta.build_absolute_uri(url)``: create an absolute URL (i.e.: complete with protocol and +domain); this is generated from the ``request`` object, if given as argument to ``as_meta``; \ No newline at end of file From 2ebc6f486a6543a0d73957cc37a04ec1bbc2ff13 Mon Sep 17 00:00:00 2001 From: Marco Federighi Date: Mon, 29 Feb 2016 11:40:00 +0100 Subject: [PATCH 6/8] Fix typo --- docs/models.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/models.rst b/docs/models.rst index 7856ac4..abc362b 100644 --- a/docs/models.rst +++ b/docs/models.rst @@ -7,7 +7,7 @@ Model support Concepts -------- -**django-meta* provides a mixin to handle metadata in your models. +**django-meta** provides a mixin to handle metadata in your models. Actual data are evaluated at runtime pulling values from model attributes and methods. From 72f1ba6858ab261e93089829a28e888e1f4977c0 Mon Sep 17 00:00:00 2001 From: Marco Federighi Date: Mon, 29 Feb 2016 11:44:34 +0100 Subject: [PATCH 7/8] Complete models doc part --- docs/models.rst | 51 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/docs/models.rst b/docs/models.rst index abc362b..9c73e88 100644 --- a/docs/models.rst +++ b/docs/models.rst @@ -50,4 +50,53 @@ implementation does not return a valid object, this **must** be overidden in the according to what is an author in the application domain; ``ModelMeta.build_absolute_uri(url)``: create an absolute URL (i.e.: complete with protocol and -domain); this is generated from the ``request`` object, if given as argument to ``as_meta``; \ No newline at end of file +domain); this is generated from the ``request`` object, if given as argument to ``as_meta``; + + +Usage +----- + +#. Configure ``django-meta`` according to documentation + +#. Add meta information to your model:: + + from django.db import models + from meta.models import ModelMeta + + class MyModel(ModelMeta, models.Model): + name = models.CharField(max_length=20) + abstract = models.TextField() + ... + + _metadata = { + 'title': 'name', + 'description': 'abstract', + ... + } + +#. Push metadata in the context using ``as_meta`` method:: + + class MyView(DetailView): + + ... + + def get_context_data(self, **kwargs): + context = super(MyView, self).get_context_data(self, **kwargs) + context['meta'] = self.get_object().as_meta(self.request) + return context + +#. Include ``meta/meta.html`` template in your templates:: + + {% load sekizai_tags %} + + + + {% include "meta/meta.html" %} + + + + + +Note +++++ +For Google+ support you must add ``{% render_block 'html_extra' %}`` in your template to add object type definition. See relevant Google+ snippets documentation (https://developers.google.com/+/web/snippet/) From e317c374803e256ec448218af8e22893411d2125 Mon Sep 17 00:00:00 2001 From: Marco Federighi Date: Mon, 29 Feb 2016 11:54:17 +0100 Subject: [PATCH 8/8] Fix reference --- docs/views.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/views.rst b/docs/views.rst index 70f30bc..af555a5 100644 --- a/docs/views.rst +++ b/docs/views.rst @@ -200,7 +200,7 @@ When the time comes to render the template, simply include the instance as ``'meta'`` context variable. The ``Meta`` instances have the same properties as the keys listed in the -`Basic concept`_ section. For convenience, some of the properties are 'smart', +`Using the view`_ section. For convenience, some of the properties are 'smart', and will modify values you set. These properties are: + keywords @@ -271,7 +271,7 @@ is very simple:: .... -The mixin sports all properties listed in the `Basic concept`_ section with a +The mixin sports all properties listed in the `Using the view`_ section with a few additional bells and whistles that make working with them easier. The mixin will return an instance of the ``Meta`` class (see `Meta objects`_) as ``meta`` context variable. This is, in turn, used in the partial template to render the