Author: batiste.bieler
Date: Mon Jul 20 10:08:13 2009
New Revision: 608
Added:
trunk/docs/Makefile
trunk/docs/conf.py
trunk/docs/index.rst
trunk/docs/installation.rst
Modified:
trunk/docs/ (props changed)
Log:
Start the sphinx documentation
Added: trunk/docs/Makefile
==============================================================================
--- (empty file)
+++ trunk/docs/Makefile Mon Jul 20 10:08:13 2009
@@ -0,0 +1,75 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d .build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
+
+help:
+ @echo "Please use \`make <target>' where <target> 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"
+
+clean:
+ -rm -rf .build/*
+
+html:
+ mkdir -p .build/html .build/doctrees
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) .build/html
+ @echo
+ @echo "Build finished. The HTML pages are in .build/html."
+
+pickle:
+ mkdir -p .build/pickle .build/doctrees
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) .build/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+web: pickle
+
+json:
+ mkdir -p .build/json .build/doctrees
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) .build/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ mkdir -p .build/htmlhelp .build/doctrees
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in .build/htmlhelp."
+
+latex:
+ mkdir -p .build/latex .build/doctrees
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in .build/latex."
+ @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+ "run these through (pdf)latex."
+
+changes:
+ mkdir -p .build/changes .build/doctrees
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) .build/changes
+ @echo
+ @echo "The overview file is in .build/changes."
+
+linkcheck:
+ mkdir -p .build/linkcheck .build/doctrees
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in .build/linkcheck/output.txt."
Added: trunk/docs/conf.py
==============================================================================
--- (empty file)
+++ trunk/docs/conf.py Mon Jul 20 10:08:13 2009
@@ -0,0 +1,190 @@
+# -*- coding: utf-8 -*-
+#
+# django-page-cms documentation build configuration file, created by
+# sphinx-quickstart on Sun Jul 19 23:15:46 2009.
+#
+# This file is execfile()d with the current directory set to its
containing dir.
+#
+# The contents of this file are pickled, so don't put values in the
namespace
+# that aren't pickleable (module imports are okay, they're removed
automatically).
+#
+# 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, os
+
+# If your extensions (or modules documented by 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.append(os.path.abspath('..'))
+
+# General configuration
+# ---------------------
+
+# 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.doctest']
+
+# 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'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'django-page-cms'
+copyright = u'2009, Batiste Bieler'
+
+# 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 = '1.0.5'
+# The full version, including alpha/beta/rc tags.
+release = '1.0.5'
+
+# 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 documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be
searched
+# for source files.
+exclude_trees = ['.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'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> 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']
+
+# 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_use_modindex = 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, the reST sources are included in the HTML build as
_sources/<name>.
+#html_copy_source = True
+
+# If true, an OpenSearch description file will be output, and all pages
will
+# contain a <link> tag referring to it. The value of this option must be
the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'django-page-cmsdoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class
[howto/manual]).
+latex_documents = [
+ ('index', 'django-page-cms.tex', ur'django-page-cms Documentation',
+ ur'Batiste Bieler', '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
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
Added: trunk/docs/index.rst
==============================================================================
--- (empty file)
+++ trunk/docs/index.rst Mon Jul 20 10:08:13 2009
@@ -0,0 +1,17 @@
+Django-page-cms's documentation
+===============================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ installation.rst
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
Added: trunk/docs/installation.rst
==============================================================================
--- (empty file)
+++ trunk/docs/installation.rst Mon Jul 20 10:08:13 2009
@@ -0,0 +1,262 @@
+============
+Installation
+============
+
+This document explain how to install django page CMS into an existing
Django project.
+This document assume that you already know how to setup a Django project.
+
+If you have any problem installing this CMS, take a look at the example
application that stands in the example directory.
+This application works out of the box and will certainly help you to get
started.
+
+Install instructions step by step
+=================================
+
+For an alternative, step by step installation process, there is this an
+OpenOffice document :
http://django-page-cms.googlegroups.com/web/gpc-install-instructions.odt
+
+Install by using pip
+====================
+
+The pip install is by far the easiest one. Use this method if you have the
choice.
+
+use::
+
+ sudo easy_install pip
+ wget -c
http://django-page-cms.googlecode.com/svn/trunk/requirements/external_apps.txt
+ sudo pip install -r external_apps.txt
+
+Every package listed in the `external_app.txt` should be downloaded and
installed.
+
+Install by using easy_install
+=============================
+
+On debian linux you can do::
+
+ sudo easy_install html5lib
+ sudo easy_install django-page-cms
+
+* Tagging must be installed by hand or with subversion* because the
available package is not
+ compatible with django 1.0.
+
+* Django-mptt must be installed by hand or with subversion* because the
available package is not compatible with django 1.0.
+
+Install by using subversion externals
+=====================================
+
+You can also use the trunk version of the Django page CMS by using
subversion externals::
+
+
+ $ svn pe svn:externals .
+ pages
http://django-page-cms.googlecode.com/svn/trunk/pages
+ mptt
http://django-mptt.googlecode.com/svn/trunk/mptt
+ tagging
http://django-tagging.googlecode.com/svn/trunk/tagging
+
+Urls
+====
+
+Take a look in the `example/urls.py` and copy desired URLs in your own
`urls.py`.
+Basically you need to have something like this::
+
+ urlpatterns = patterns('',
+ ...
+ url(r'^pages/', include('pages.urls')),
+ (r'^admin/(.*)', admin.site.root),
+ )
+
+When you will visit the site the first time (`/pages/`), you will get a
404 error
+because there is no published page. Go to the admin first and create and
publish some pages.
+
+You will certainly want to activate the static file serve view in your
`urls.py` if you are in developement mode::
+
+ if settings.DEBUG:
+ urlpatterns += patterns('',
+ # Trick for Django to support static files (security hole:
only for Dev environement! remove this on Prod!!!)
+ url(r'^media/(?P<path>.*)$', 'django.views.static.serve',
{'document_root': settings.MEDIA_ROOT}),
+
url(r'^admin_media/(?P<path>.*)$', 'django.views.static.serve',
{'document_root': settings.ADMIN_MEDIA_ROOT}),
+ )
+
+Settings
+========
+
+All the Django page CMS specific settings and options are listed and
explained in the `pages/settings.py` file.
+
+Django page CMS require several of these settings to be set. They are
marked in this document with a bold "*must*".
+
+Tagging
+-------
+
+Tagging is optional and disabled by default.
+
+If you want to use it set `PAGE_TAGGING` at `True` into your setting file
and add it to your installed apps::
+
+ INSTALLED_APPS = (
+ 'django.contrib.auth',
+ 'django.contrib.contenttypes',
+ 'django.contrib.sessions',
+ 'django.contrib.admin',
+ 'django.contrib.sites',
+ 'mptt',
+ 'tagging',
+ 'pages',
+ ...
+ )
+
+Caching
+-------
+
+Django page CMS use the caching framework quite intensively. You should
definitely
+setting-up a cache-backend_ to have decent performance.
+
+.. _cache-backend:
http://docs.djangoproject.com/en/dev/topics/cache/#setting-up-the-cache
+
+If you cannot setup memcache or a database cache, you can use the local
memory cache this way::
+
+ CACHE_BACKEND = "locmem:///?max_entries=5000"
+
+Languages
+---------
+
+Please first read how django handle languages
+
+* http://docs.djangoproject.com/en/dev/ref/settings/#languages
+* http://docs.djangoproject.com/en/dev/ref/settings/#language-code
+
+This CMS use the `PAGE_LANGUAGES` setting in order to present which
language are supported by the CMS.
+By default `PAGE_LANGUAGES` value is set to `settings.LANGUAGES` value.
+So you can directly set the `LANGUAGES` setting if you want.
+In any case *you should set* `PAGE_LANGUAGES` or `LANGUAGES`
+yourself because by default the `LANGUAGES` list is big.
+
+Django use `LANGUAGES` setting to set the `request.LANGUAGE_CODE` value
that is used by this CMS. So if the language you want to support is not
present in the `LANGUAGES` setting the `request.LANGUAGE_CODE` will not be
set correctly.
+
+A possible solution is to redefine `settings.LANGUAGES`. For example you
can do::
+
+ # Default language code for this installation. All choices can be
found here:
+ # http://www.i18nguy.com/unicode/language-identifiers.html
+ LANGUAGE_CODE = 'en-us'
+
+ # This is defined here as a do-nothing function because we can't import
+ # django.utils.translation -- that module depends on the settings.
+ gettext_noop = lambda s: s
+
+ # here is all the languages supported by the CMS
+ PAGE_LANGUAGES = (
+ ('de', gettext_noop('German')),
+ ('fr-ch', gettext_noop('Swiss french')),
+ ('en-us', gettext_noop('US English')),
+ )
+
+ # copy PAGE_LANGUAGES
+ languages = list(PAGE_LANGUAGES)
+
+ # All language accepted as a valid client language
+ languages.append(('fr-fr', gettext_noop('French')))
+ languages.append(('fr-be', gettext_noop('Belgium french')))
+ # redefine the LANGUAGES setting in order to set request.LANGUAGE_CODE
correctly
+ LANGUAGES = languages
+
+Template context processors and Middlewares
+-------------------------------------------
+
+You *must* have these context processors into your
`TEMPLATE_CONTEXT_PROCESSORS` setting::
+
+ TEMPLATE_CONTEXT_PROCESSORS = (
+ 'django.core.context_processors.auth',
+ 'django.core.context_processors.i18n',
+ 'django.core.context_processors.debug',
+ 'django.core.context_processors.media',
+ 'django.core.context_processors.request',
+ 'pages.context_processors.media',
+ ...
+ )
+
+You *must* have these middleware into your `MIDDLEWARE_CLASSES` setting::
+
+ MIDDLEWARE_CLASSES = (
+ 'django.contrib.sessions.middleware.SessionMiddleware',
+ 'django.middleware.common.CommonMiddleware',
+ 'django.contrib.auth.middleware.AuthenticationMiddleware',
+ 'django.middleware.doc.XViewMiddleware',
+ 'django.middleware.locale.LocaleMiddleware',
+ ...
+ )
+
+Default template
+----------------
+
+You *must* set `DEFAULT_PAGE_TEMPLATE` to the name of your default CMS
template::
+
+ DEFAULT_PAGE_TEMPLATE = 'pages/index.html'
+
+And you *must* copy the directory `example/templates/pages` into your root
template directory.
+
+Additional templates
+--------------------
+
+Optionally you can set `PAGE_TEMPLATES` if you want additional templates
choices.
+In the the example application you have actually this::
+
+ PAGE_TEMPLATES = (
+ ('pages/nice.html', 'nice one'),
+ ('pages/cool.html', 'cool one'),
+ )
+
+The sites framework
+-------------------
+
+If you want to use the
http://docs.djangoproject.com/en/dev/ref/contrib/sites/#ref-contrib-sites
Django sites framework] with django-page-cms, you *must* define the
`SITE_ID` and `PAGE_USE_SITE_ID` settings and create the appropriate Site
object into the admin interface::
+
+ PAGE_USE_SITE_ID = True
+ SITE_ID = 1
+
+The Site object should have the domain that match your actual domain (ie:
127.0.0.1:8000)
+
+Media directory
+---------------
+
+The django CMS come with some javascript and CSS files. These files are
standing in the `pages/media/pages` directory.
+
+If you don't know how to serve static files with Django please read :
+
+http://docs.djangoproject.com/en/dev/howto/static-files/
+
+
+Django CMS has a special setting called `PAGES_MEDIA_URL` that enable you
to change
+how the browser will ask for these files in the CMS admin. By default the
value of `PAGES_MEDIA_URL` is set to ::
+
+ PAGES_MEDIA_URL = getattr(settings, 'PAGES_MEDIA_URL',
join(settings.MEDIA_URL, 'pages/'))
+
+Or in a simpler way::
+
+
+ PAGES_MEDIA_URL = settings.MEDIA_URL + "pages/"
+
+
+In the CMS admin template you have::
+
+
+ <link rel="stylesheet" type="text/css" href="{{ PAGES_MEDIA_URL
}}css/pages.css" />
+ <script type="text/javascript" src="{{ PAGES_MEDIA_URL
}}javascript/jquery.js"></script>
+
+
+That will be rendered by default like this if `MEDIA_URL == '/media/'`::
+
+
+ <link rel="stylesheet" type="text/css"
href="/media/pages/css/pages.css" />
+ <script type="text/javascript"
src="/media/pages/javascript/jquery.js"></script>
+
+You can off course redefine this variable in your setting file if you are
not happy with this default
+
+In any case you must at least create a symbolic link or copy the directory
`pages/media/pages/` into
+your media directory to have a fully functioning administration interface.
+
+The example application take another approch by directly
+point the `MEDIA_ROOT` of the project on the `page/media` directory::
+
+ # Absolute path to the directory that holds media.
+ MEDIA_ROOT = os.path.join(PROJECT_DIR, '../pages/media/')
+ ADMIN_MEDIA_ROOT = os.path.join(PROJECT_DIR, '../admin_media/')
+ MEDIA_URL = '/media/'
+ ADMIN_MEDIA_PREFIX = '/admin_media/'
+
+But you certainly want to redefine these variables to your own project
media directory.
\ No newline at end of file
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"pinax-updates" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/pinax-updates?hl=en
-~----------~----~----~----~------~----~------~--~---
