From 01166165bee89dfc11e69589fd05a9e74e0aeea1 Mon Sep 17 00:00:00 2001 From: Étienne Loks Date: Wed, 5 Dec 2012 17:24:15 +0100 Subject: Documentation: reorganization to generate multi-languages docs --- docs/Makefile | 130 --------- docs/_static/chimere_admin_00.png | Bin 5855 -> 0 bytes docs/_static/chimere_admin_01.png | Bin 69448 -> 0 bytes docs/_static/chimere_admin_02.png | Bin 62730 -> 0 bytes docs/_static/chimere_admin_03.png | Bin 65588 -> 0 bytes docs/_static/chimere_admin_import_CSV.png | Bin 12579 -> 0 bytes docs/_static/chimere_admin_import_KML.png | Bin 14953 -> 0 bytes docs/_static/chimere_admin_import_OSM.png | Bin 113738 -> 0 bytes docs/_static/chimere_admin_import_georss.png | Bin 10260 -> 0 bytes docs/_static/chimere_admin_import_shapefile.png | Bin 13807 -> 0 bytes docs/_static/chimere_admin_modified_management.png | Bin 93852 -> 0 bytes docs/_static/chimere_admin_modify_item.png | Bin 109282 -> 0 bytes docs/administration.rst | 209 -------------- docs/conf.py | 216 -------------- docs/configuration.rst | 187 ------------- docs/customisation.rst | 52 ---- docs/en/Makefile | 130 +++++++++ docs/en/administration.rst | 209 ++++++++++++++ docs/en/conf.py | 216 ++++++++++++++ docs/en/configuration.rst | 187 +++++++++++++ docs/en/customisation.rst | 52 ++++ docs/en/import_export.rst | 235 ++++++++++++++++ docs/en/index.rst | 17 ++ docs/en/install.rst | 290 +++++++++++++++++++ docs/en/static/chimere_admin_00.png | Bin 0 -> 5855 bytes docs/en/static/chimere_admin_01.png | Bin 0 -> 69448 bytes docs/en/static/chimere_admin_02.png | Bin 0 -> 62730 bytes docs/en/static/chimere_admin_03.png | Bin 0 -> 65588 bytes docs/en/static/chimere_admin_import_CSV.png | Bin 0 -> 12579 bytes docs/en/static/chimere_admin_import_KML.png | Bin 0 -> 14953 bytes docs/en/static/chimere_admin_import_OSM.png | Bin 0 -> 113738 bytes docs/en/static/chimere_admin_import_georss.png | Bin 0 -> 10260 bytes docs/en/static/chimere_admin_import_shapefile.png | Bin 0 -> 13807 bytes .../static/chimere_admin_modified_management.png | Bin 0 -> 93852 bytes docs/en/static/chimere_admin_modify_item.png | Bin 0 -> 109282 bytes docs/en/upgrade.rst | 311 +++++++++++++++++++++ docs/fr/Makefile | 130 +++++++++ docs/fr/administration.rst | 12 +- docs/fr/conf.py | 216 ++++++++++++++ docs/fr/import_export.rst | 10 +- docs/fr/static/chimere_admin_00.png | Bin 0 -> 5855 bytes docs/fr/static/chimere_admin_01.png | Bin 0 -> 69448 bytes docs/fr/static/chimere_admin_02.png | Bin 0 -> 62730 bytes docs/fr/static/chimere_admin_03.png | Bin 0 -> 65588 bytes docs/fr/static/chimere_admin_import_CSV.png | Bin 0 -> 12579 bytes docs/fr/static/chimere_admin_import_KML.png | Bin 0 -> 14953 bytes docs/fr/static/chimere_admin_import_OSM.png | Bin 0 -> 113738 bytes docs/fr/static/chimere_admin_import_georss.png | Bin 0 -> 10260 bytes docs/fr/static/chimere_admin_import_shapefile.png | Bin 0 -> 13807 bytes .../static/chimere_admin_modified_management.png | Bin 0 -> 93852 bytes docs/fr/static/chimere_admin_modify_item.png | Bin 0 -> 109282 bytes docs/import_export.rst | 235 ---------------- docs/index.rst | 17 -- docs/install.rst | 290 ------------------- docs/upgrade.rst | 311 --------------------- 55 files changed, 2004 insertions(+), 1658 deletions(-) delete mode 100644 docs/Makefile delete mode 100644 docs/_static/chimere_admin_00.png delete mode 100644 docs/_static/chimere_admin_01.png delete mode 100644 docs/_static/chimere_admin_02.png delete mode 100644 docs/_static/chimere_admin_03.png delete mode 100644 docs/_static/chimere_admin_import_CSV.png delete mode 100644 docs/_static/chimere_admin_import_KML.png delete mode 100644 docs/_static/chimere_admin_import_OSM.png delete mode 100644 docs/_static/chimere_admin_import_georss.png delete mode 100644 docs/_static/chimere_admin_import_shapefile.png delete mode 100644 docs/_static/chimere_admin_modified_management.png delete mode 100644 docs/_static/chimere_admin_modify_item.png delete mode 100644 docs/administration.rst delete mode 100644 docs/conf.py delete mode 100644 docs/configuration.rst delete mode 100644 docs/customisation.rst create mode 100644 docs/en/Makefile create mode 100644 docs/en/administration.rst create mode 100644 docs/en/conf.py create mode 100644 docs/en/configuration.rst create mode 100644 docs/en/customisation.rst create mode 100644 docs/en/import_export.rst create mode 100644 docs/en/index.rst create mode 100644 docs/en/install.rst create mode 100644 docs/en/static/chimere_admin_00.png create mode 100644 docs/en/static/chimere_admin_01.png create mode 100644 docs/en/static/chimere_admin_02.png create mode 100644 docs/en/static/chimere_admin_03.png create mode 100644 docs/en/static/chimere_admin_import_CSV.png create mode 100644 docs/en/static/chimere_admin_import_KML.png create mode 100644 docs/en/static/chimere_admin_import_OSM.png create mode 100644 docs/en/static/chimere_admin_import_georss.png create mode 100644 docs/en/static/chimere_admin_import_shapefile.png create mode 100644 docs/en/static/chimere_admin_modified_management.png create mode 100644 docs/en/static/chimere_admin_modify_item.png create mode 100644 docs/en/upgrade.rst create mode 100644 docs/fr/Makefile create mode 100644 docs/fr/conf.py create mode 100644 docs/fr/static/chimere_admin_00.png create mode 100644 docs/fr/static/chimere_admin_01.png create mode 100644 docs/fr/static/chimere_admin_02.png create mode 100644 docs/fr/static/chimere_admin_03.png create mode 100644 docs/fr/static/chimere_admin_import_CSV.png create mode 100644 docs/fr/static/chimere_admin_import_KML.png create mode 100644 docs/fr/static/chimere_admin_import_OSM.png create mode 100644 docs/fr/static/chimere_admin_import_georss.png create mode 100644 docs/fr/static/chimere_admin_import_shapefile.png create mode 100644 docs/fr/static/chimere_admin_modified_management.png create mode 100644 docs/fr/static/chimere_admin_modify_item.png delete mode 100644 docs/import_export.rst delete mode 100644 docs/index.rst delete mode 100644 docs/install.rst delete mode 100644 docs/upgrade.rst (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index dc549a6..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,130 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -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 $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest - -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 " text to make text files" - @echo " man to make manual pages" - @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 $(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/Chimre.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Chimre.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/Chimre" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Chimre" - @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." - -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." - -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." diff --git a/docs/_static/chimere_admin_00.png b/docs/_static/chimere_admin_00.png deleted file mode 100644 index 374c6b6..0000000 Binary files a/docs/_static/chimere_admin_00.png and /dev/null differ diff --git a/docs/_static/chimere_admin_01.png b/docs/_static/chimere_admin_01.png deleted file mode 100644 index 0db7f4d..0000000 Binary files a/docs/_static/chimere_admin_01.png and /dev/null differ diff --git a/docs/_static/chimere_admin_02.png b/docs/_static/chimere_admin_02.png deleted file mode 100644 index d0fd6fe..0000000 Binary files a/docs/_static/chimere_admin_02.png and /dev/null differ diff --git a/docs/_static/chimere_admin_03.png b/docs/_static/chimere_admin_03.png deleted file mode 100644 index e815500..0000000 Binary files a/docs/_static/chimere_admin_03.png and /dev/null differ diff --git a/docs/_static/chimere_admin_import_CSV.png b/docs/_static/chimere_admin_import_CSV.png deleted file mode 100644 index e67a37b..0000000 Binary files a/docs/_static/chimere_admin_import_CSV.png and /dev/null differ diff --git a/docs/_static/chimere_admin_import_KML.png b/docs/_static/chimere_admin_import_KML.png deleted file mode 100644 index b48d69a..0000000 Binary files a/docs/_static/chimere_admin_import_KML.png and /dev/null differ diff --git a/docs/_static/chimere_admin_import_OSM.png b/docs/_static/chimere_admin_import_OSM.png deleted file mode 100644 index a599348..0000000 Binary files a/docs/_static/chimere_admin_import_OSM.png and /dev/null differ diff --git a/docs/_static/chimere_admin_import_georss.png b/docs/_static/chimere_admin_import_georss.png deleted file mode 100644 index 5278652..0000000 Binary files a/docs/_static/chimere_admin_import_georss.png and /dev/null differ diff --git a/docs/_static/chimere_admin_import_shapefile.png b/docs/_static/chimere_admin_import_shapefile.png deleted file mode 100644 index ce612be..0000000 Binary files a/docs/_static/chimere_admin_import_shapefile.png and /dev/null differ diff --git a/docs/_static/chimere_admin_modified_management.png b/docs/_static/chimere_admin_modified_management.png deleted file mode 100644 index 84e069e..0000000 Binary files a/docs/_static/chimere_admin_modified_management.png and /dev/null differ diff --git a/docs/_static/chimere_admin_modify_item.png b/docs/_static/chimere_admin_modify_item.png deleted file mode 100644 index 861ea20..0000000 Binary files a/docs/_static/chimere_admin_modify_item.png and /dev/null differ diff --git a/docs/administration.rst b/docs/administration.rst deleted file mode 100644 index 672caa9..0000000 --- a/docs/administration.rst +++ /dev/null @@ -1,209 +0,0 @@ -.. -*- coding: utf-8 -*- -.. _administration: - -============== -Administration -============== - -:Author: Étienne Loks -:date: 2012-11-28 -:Copyright: CC-BY 3.0 - -This document presents the administration of Chimère. -It has been updated for version 2.0.0. - - -Administration pages presentation ---------------------------------- - -Administration pages are accessible at: http://where_is_your_chimere/admin/ - -Don't forget the ending slash in the URL. - -Identification -************** - -First of all, you'll have to identify yourself with the login and password -provided. - -.. image:: _static/chimere_admin_00.png - - -Main page -********* - -Once authentified you'll have access to the main admin page. - -It looks like this: - -.. image:: _static/chimere_admin_01.png - -#. links to this **Documentation**, to the **Change password** form and to - **Log out**, -#. the list of recent actions made with this account, -#. an application title, most of your action will be in the **Chimere** - application, -#. an item inside the application. From these pages you can **Add** a new item or - consult/**Change** items. The **Add** link leads to the new `Item form`_. The - **Change** link leads to the `Item list`_. The `Item list`_ is also available - by clicking on the item label. - - -Item list -********* - -.. image:: _static/chimere_admin_02.png - -#. path in the admin site. This is a convenient shortcut to come back to the - main page, -#. link to create a new item from the item list, -#. search items by words (not available for all item types), -#. this filter box permits to filter current entries with some criteria (not - available for all type of items), -#. the header of the table is clickable. Clicking on an header sorts the items by - this header (ascending or descending). Multiple header sort is possible (the - number on the right of the header explains the sorting order), -#. each item can be checked (for applying an action) or selected (by clicking on - the first column) to see the detail and edit or delete it. - -Item form -********* - -.. image:: _static/chimere_admin_03.png - -#. fields for the selected item (or blank if it is a new item) are displayed in - this form. A few fields are read-only and another few are hidden. Mandatory - fields have their label in bold. Changes on these fields are only effective - once the form is submitted. -#. for some items there are associated sub-items. These associated items can be - modified in this form. If there are many sub-items associated for the current - item, they can be ordered by drag and drop. -#. the form has to be validated by one of these action buttons. They are - self-explanatory. - -Status -****** - -*Status* is a property attached to each geographic item in Chimère. To -administrate efficiently Chimère you need to understand the mean of each status. - -- **Submitted**: Status of a new item freshly proposed by an end user. This item - is not visible on the map. -- **Available**: Status of an item visible on the map. -- **Disabled**: Status of a discarded item. -- **Modified**: Status of an amendment proposed by an end-user. -- **Imported**: Status of a newly imported item. Import and export operations - need that all items with *imported* status are treated (validated, disabled - or deleted). - - -Managing news -------------- - -A news system is available. -All you have to to do is to click on the **Add** button near News. -For each news you have to provide a name and a content. The content can contain -HTML tags. -The availability is set with a checkbox. - -Creating categories/subcategories ---------------------------------- - -Before adding categories you have to set some icons. These icons appear on the -map and in the categories' box on the main map. -Be careful to resize correctly your icons. Indeed the icon will be presented at -their real size on the map. -To add icons: the **Add** button near Icons. - -Categories are in fact only containers for subcategories. You'll have to provide -only a name and an order. -To add categories: the **Add** button near categories (quite clear now, isn't -it?) - -Fields of subcategories are: an associated category, a name, an icon, an order, -a color and an element type. -These fields are mainly quite self- explanatory. -The color is used to draw routes (if this subcategory contains routes). If it a -basic color it can be set with the English name (for instance: *red*, *blue*, -*yellow* or *purple*) otherwise you can put the HTML RVB code (for instance -*#9227c9*). -The element type is the type of element that the subcategory can contain: POI, route -or both. - -.. _geographic-items-management: - -Editing or moderating items ---------------------------- - -The moderation step is quite simple. It works the same with POIs and routes. -The moderator can access to all POIs (or routes) by clicking on them on the -list. - -A search field is available to search by name but the more interesting is to -filter POIs (or route) by state and by subcategory. - -There are some actions available in the action list: - -- **Delete**: to delete selected items. A confirmation step is displayed, -- **Validate**: to set the status *Available* to selected items, -- **Disable**: to set the status *Disabled* to selected items. This is useful to - keep items you don't want to be exposed on the map, -- **Managed modified items**: to manage the amendment made by end users on the - main site (cf. :ref:`managing-modified`). Modified item has to be treated - one by one, -- **Export to...**: to export selected item to the selected format. - - -To modify an item, classically you have to click on its name. -Then you access to a form to freely modify the item. - -.. image:: _static/chimere_admin_modify_item.png - -In this form there are all data available to the end user form plus some extra -fields. - -- The *Import fields* only make sense with data imported from an external - source or for data to be exported to OSM (cf. the :ref:`import section - ` of this documentation), -- *Associated items fields* are read-only fields that list items associated to - the current one (for example the reference item of an amendment or an associated - file of a route). - -Associated multimedia items are at the bottom of the form. You can freely add, -change items and change their order with drag and drop. - -Don't forget to validate your change with one of the **Save** buttons at the -bottom of the form (it is easily forgotten when you change multimedia items). - -If an item is not relevant the **Delete** button enables to remove it. - -.. _managing-modified: - -Managing end user amendment ---------------------------- - -Amendment can be proposed on the main site by end-users. -In Chimère an amendment is a new item with the status *Modified* and with a link -to the reference item modified. - -.. Note:: - If you are logged as an administrator and make changes on the map with the - end user form they will be directly validated. - -A special form has been developed to facilitate the processing of these -modified items. - -You can access to this special form with the action *Managed modified items*. - -.. image:: _static/chimere_admin_modified_management.png - -This form is a table with three columns: - -#. The first column displays the information for the reference item, -#. The second column displays the information proposed by the submitter, -#. The third column is a list of checkboxes. For each row checked, after the - validation, the value of the modified item will replace the value of the - reference item. - -.. Note:: - To reject all modifications validate the form with no checkbox checked. diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 9221eb1..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,216 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Chimère documentation build configuration file, created by -# sphinx-quickstart on Wed Feb 15 00:42:28 2012. -# -# 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, 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('.')) - -# -- 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 = [] - -# 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'Chimère' -copyright = u'2012, Étienne Loks' - -# 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 = '2.0' -# The full version, including alpha/beta/rc tags. -release = '2.0' - -# 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 = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'default' - -# 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'] - -# 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 = 'Chimredoc' - - -# -- 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, documentclass [howto/manual]). -latex_documents = [ - ('index', 'Chimre.tex', u'Chimère Documentation', - u'Étienne Loks', '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 - -# 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_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', 'chimre', u'Chimère Documentation', - [u'Étienne Loks'], 1) -] diff --git a/docs/configuration.rst b/docs/configuration.rst deleted file mode 100644 index e5870bb..0000000 --- a/docs/configuration.rst +++ /dev/null @@ -1,187 +0,0 @@ -.. -*- coding: utf-8 -*- - -============= -Configuration -============= - -:Author: Étienne Loks -:date: 2012-10-08 -:Copyright: CC-BY 3.0 - -This document presents the first steps to configure your Chimère. -It has been updated for version 2.0.0. - -Your session has to be initialised with these environment variables in -the Command Line Interface:: - - CHIMERE_PATH=/srv/chimere # change with your installation path - CHIMERE_LOCALNAME=mychimere # change with your local project name - CHIMERE_APP_PATH=$CHIMERE_PATH/$CHIMERE_LOCALNAME - - -Once the application installed, there are a few simple steps to follow to -configure *your* Chimère. - -Most of these steps are done in the web administration pages. - -If you are not familiar with *Django-like* administration pages you can look -at the first paragraph of :ref:`administration` where it is presented. - -To access these pages you have to identify with an account with *staff* and -*superuser* status. - -A *superuser* account is created at the initialization of the database. - -Configuring the Sites framework -------------------------------- - -*Sites* framework allow you to serve the same content on different domains. -Most of you will probably use only one domain but this unique domain has to -be configured. This is done in the web administration interface in *Sites > Sites*. -You only need to change *example.com* by your domain name. If you forget to -do that, some functionalities such as RSS feeds will not work properly. - -.. _managing-areas: - -Managing areas --------------- - -An *Area* is the base of your map. It defines: - -* a name: a human readable label for this area, -* an associated URN (*not mandatory*): the name of the area as a web ressource. - In practice, if the area is not the default area the URN is used at the end of - the default URL to access to this area. This is not mandatory but necessary - for each area that is not the default one, -* a welcome message (*not mandatory*): this message is displayed once a day per - user arriving on the map, -* an order (to sort areas), -* an availability, -* a "*default*" state. The "*default*" area is viewed by default. Only one area - can be the default: activating this state disables it on the possible other - area with a default state, -* default checked categories (*not mandatory*), -* if categories are displayed dynamically. If dynamically is set, the end user - only views categories which have items on the map section he is currently - looking at, -* categories restriction (*not mandatory*): if no restriction is set all - categories are available, -* an external CSS file (*not mandatory*): an URL to an external CSS file, -* restriction on the bounding box: if set to restricted, the end user can't pan - outside the defined bounding box. Due to technical reasons of OpenLayers, - there is at this time no restriction on the zoom, -* a map bounding box: this is the area to display when arriving on the map. If - the area is restricted it will be the bounding box that restricts the end - user. Hold the *control* key, click and drag to draw the bounding box, -* available layers (*not mandatory*: OSM Mapnik is used by default): OSM - Mapnik render, OSM MapQuest render, OSM Transport Map render, OSM CycleMap are - available by default. You can add new custom layers (cf. - :ref:`managing-layers`). - -*Areas* are customizable directly on the web administration interface in -*Chimere > Areas*. - -As there is little chance that the default area should be appropriated for you, -you'll have to set at least one default area. - -Adding many areas can be a mean to show your map in different flavors. - -Managing users --------------- - -If you are not the only administrator/moderator of this Chimère installation -you have to create and manage account for the other users. - -You can create a new *superuser* account with the Command Line Interface (CLI):: - - ./manage.py createsuperuser - -User password can be changed with the CLI (useful if you have forgotten your -password):: - - ./manage.py changepassword username - -*Users* are customizable directly on the web administration interface in -*Auth/User*. - -To create a new account, simply click on the *Add* button near *Users*. Give a -name and a default password (the user can change it on his own later). - -Then complete the other pieces of information. - -Check the case: *Staff status* (or this user will not be able to log to the -administration website). - -If this account is a new technical administrator, check *Superuser status* (this -user must be trustworthy!). Otherwise you'll have to give permissions to this -new user. It is easier not to add permission manually but to make this user -a member of a group. - -Two types of default group are proposed: application administrator and -moderator. - -Moderator are limited to an *Area* (they only see items that are inside the -bounding box). If a moderator manages many areas you'll have to select many -groups. - -Detail of rights for default groups: - -+-----------------------------------------+-------------------------+---------------------------+-----------+ -| Item (add/modify/delete on) | Technical administrator | Application administrator | Moderator | -+=========================================+=========================+===========================+===========+ -| User | yes | no | no | -+-----------------------------------------+-------------------------+---------------------------+-----------+ -| Group | yes | no | no | -+-----------------------------------------+-------------------------+---------------------------+-----------+ -| Property model | yes | no | no | -+-----------------------------------------+-------------------------+---------------------------+-----------+ -| Import | yes | no | no | -+-----------------------------------------+-------------------------+---------------------------+-----------+ -| Layer | yes | no | no | -+-----------------------------------------+-------------------------+---------------------------+-----------+ -| News | yes | yes | no | -+-----------------------------------------+-------------------------+---------------------------+-----------+ -| Area | yes | yes | no | -+-----------------------------------------+-------------------------+---------------------------+-----------+ -| Icon | yes | yes | no | -+-----------------------------------------+-------------------------+---------------------------+-----------+ -| Color/Color theme | yes | yes | no | -+-----------------------------------------+-------------------------+---------------------------+-----------+ -| Category/Subcategory | yes | yes | no | -+-----------------------------------------+-------------------------+---------------------------+-----------+ -| Point Of Interest | yes | yes | yes | -+-----------------------------------------+-------------------------+---------------------------+-----------+ -| Route | yes | yes | yes | -+-----------------------------------------+-------------------------+---------------------------+-----------+ - - -Creating property models ------------------------- - -A basic installation of Chimère permits to associate a name, a category, a -description, dates, multimedia files, picture files, etc. for each geographic -item. - -You may want to add more custom fields like phone number or opening hours. For -that all you have to do is to add a new property model (*Chimere/Property -model*). - -The administration page asks you for: - -* a name, -* an order (to sort properties), -* an availability to the end user (this can be used to set hidden properties), -* a mandatory status, -* the categories the property applies to (if no categories selected it applies - to all), -* the type: text, long text, password or date. - -To make this property available it is necessary to reload your web server (the -property is cached). - -All forms are then automatically updated with this new field. - -If you don't want to allow add and modification of properties you can disable -this form by setting CHIMERE_HIDE_PROPERTYMODEL to *True* in your -*local_settings.py* file. - diff --git a/docs/customisation.rst b/docs/customisation.rst deleted file mode 100644 index 665e2f8..0000000 --- a/docs/customisation.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. -*- coding: utf-8 -*- - -============= -Customisation -============= - -:Author: Étienne Loks -:date: 2012-11-28 -:Copyright: CC-BY 3.0 - -This document presents the customisation of Chimère. -It has been updated for version 2.0.0. - - -.. _managing-layers: - -Managing layers ---------------- - -There are some different layers available by default in Chimère (OSM Mapnik, OSM -Mapquest, OSM Transport map, OSM Cyclemap). You can add some extra layer using -the web administration pages of Chimère. The new layer is defined with the -appropriate `Openlayers `_ JS code. This JS code must -be a compatible Openlayers Layer instance with no ending semi-colon. For -instance defining a Bing layer can be done with this kind of code:: - - new OpenLayers.Layer.Bing({ - name: "Aerial", - key: "my-bing-API-key", - type: "Aerial"}) - - -Refer to the `Openlayers documentation API -`_ -for more details. - - -Customizing the layout and the design -------------------------------------- - -If you only want to customize the CSS, the easiest way to do it is to add a -link to an extra CSS to your *Areas* cf. :ref:`managing-areas`. - -If you want to do larger changes in the layout and the style the (well named) -example_project can be customized to fit your needs. Each template file present -in the *chimere/templates* directory can be copied in your *myproject/templates* -directory and then modified. -You only need to copy files that you want to modify. These files are in -Django template language mainly made of pure HTML with some logic. Refer to -the `Django template documentation `_ -for more details. - diff --git a/docs/en/Makefile b/docs/en/Makefile new file mode 100644 index 0000000..fcccf30 --- /dev/null +++ b/docs/en/Makefile @@ -0,0 +1,130 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +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 $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +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 " text to make text files" + @echo " man to make manual pages" + @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 $(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/Chimre.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Chimre.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/Chimre" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Chimre" + @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." + +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." + +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." diff --git a/docs/en/administration.rst b/docs/en/administration.rst new file mode 100644 index 0000000..8b7e581 --- /dev/null +++ b/docs/en/administration.rst @@ -0,0 +1,209 @@ +.. -*- coding: utf-8 -*- +.. _administration: + +============== +Administration +============== + +:Author: Étienne Loks +:date: 2012-11-28 +:Copyright: CC-BY 3.0 + +This document presents the administration of Chimère. +It has been updated for version 2.0.0. + + +Administration pages presentation +--------------------------------- + +Administration pages are accessible at: http://where_is_your_chimere/admin/ + +Don't forget the ending slash in the URL. + +Identification +************** + +First of all, you'll have to identify yourself with the login and password +provided. + +.. image:: static/chimere_admin_00.png + + +Main page +********* + +Once authentified you'll have access to the main admin page. + +It looks like this: + +.. image:: static/chimere_admin_01.png + +#. links to this **Documentation**, to the **Change password** form and to + **Log out**, +#. the list of recent actions made with this account, +#. an application title, most of your action will be in the **Chimere** + application, +#. an item inside the application. From these pages you can **Add** a new item or + consult/**Change** items. The **Add** link leads to the new `Item form`_. The + **Change** link leads to the `Item list`_. The `Item list`_ is also available + by clicking on the item label. + + +Item list +********* + +.. image:: static/chimere_admin_02.png + +#. path in the admin site. This is a convenient shortcut to come back to the + main page, +#. link to create a new item from the item list, +#. search items by words (not available for all item types), +#. this filter box permits to filter current entries with some criteria (not + available for all type of items), +#. the header of the table is clickable. Clicking on an header sorts the items by + this header (ascending or descending). Multiple header sort is possible (the + number on the right of the header explains the sorting order), +#. each item can be checked (for applying an action) or selected (by clicking on + the first column) to see the detail and edit or delete it. + +Item form +********* + +.. image:: static/chimere_admin_03.png + +#. fields for the selected item (or blank if it is a new item) are displayed in + this form. A few fields are read-only and another few are hidden. Mandatory + fields have their label in bold. Changes on these fields are only effective + once the form is submitted. +#. for some items there are associated sub-items. These associated items can be + modified in this form. If there are many sub-items associated for the current + item, they can be ordered by drag and drop. +#. the form has to be validated by one of these action buttons. They are + self-explanatory. + +Status +****** + +*Status* is a property attached to each geographic item in Chimère. To +administrate efficiently Chimère you need to understand the mean of each status. + +- **Submitted**: Status of a new item freshly proposed by an end user. This item + is not visible on the map. +- **Available**: Status of an item visible on the map. +- **Disabled**: Status of a discarded item. +- **Modified**: Status of an amendment proposed by an end-user. +- **Imported**: Status of a newly imported item. Import and export operations + need that all items with *imported* status are treated (validated, disabled + or deleted). + + +Managing news +------------- + +A news system is available. +All you have to to do is to click on the **Add** button near News. +For each news you have to provide a name and a content. The content can contain +HTML tags. +The availability is set with a checkbox. + +Creating categories/subcategories +--------------------------------- + +Before adding categories you have to set some icons. These icons appear on the +map and in the categories' box on the main map. +Be careful to resize correctly your icons. Indeed the icon will be presented at +their real size on the map. +To add icons: the **Add** button near Icons. + +Categories are in fact only containers for subcategories. You'll have to provide +only a name and an order. +To add categories: the **Add** button near categories (quite clear now, isn't +it?) + +Fields of subcategories are: an associated category, a name, an icon, an order, +a color and an element type. +These fields are mainly quite self- explanatory. +The color is used to draw routes (if this subcategory contains routes). If it a +basic color it can be set with the English name (for instance: *red*, *blue*, +*yellow* or *purple*) otherwise you can put the HTML RVB code (for instance +*#9227c9*). +The element type is the type of element that the subcategory can contain: POI, route +or both. + +.. _geographic-items-management: + +Editing or moderating items +--------------------------- + +The moderation step is quite simple. It works the same with POIs and routes. +The moderator can access to all POIs (or routes) by clicking on them on the +list. + +A search field is available to search by name but the more interesting is to +filter POIs (or route) by state and by subcategory. + +There are some actions available in the action list: + +- **Delete**: to delete selected items. A confirmation step is displayed, +- **Validate**: to set the status *Available* to selected items, +- **Disable**: to set the status *Disabled* to selected items. This is useful to + keep items you don't want to be exposed on the map, +- **Managed modified items**: to manage the amendment made by end users on the + main site (cf. :ref:`managing-modified`). Modified item has to be treated + one by one, +- **Export to...**: to export selected item to the selected format. + + +To modify an item, classically you have to click on its name. +Then you access to a form to freely modify the item. + +.. image:: static/chimere_admin_modify_item.png + +In this form there are all data available to the end user form plus some extra +fields. + +- The *Import fields* only make sense with data imported from an external + source or for data to be exported to OSM (cf. the :ref:`import section + ` of this documentation), +- *Associated items fields* are read-only fields that list items associated to + the current one (for example the reference item of an amendment or an associated + file of a route). + +Associated multimedia items are at the bottom of the form. You can freely add, +change items and change their order with drag and drop. + +Don't forget to validate your change with one of the **Save** buttons at the +bottom of the form (it is easily forgotten when you change multimedia items). + +If an item is not relevant the **Delete** button enables to remove it. + +.. _managing-modified: + +Managing end user amendment +--------------------------- + +Amendment can be proposed on the main site by end-users. +In Chimère an amendment is a new item with the status *Modified* and with a link +to the reference item modified. + +.. Note:: + If you are logged as an administrator and make changes on the map with the + end user form they will be directly validated. + +A special form has been developed to facilitate the processing of these +modified items. + +You can access to this special form with the action *Managed modified items*. + +.. image:: static/chimere_admin_modified_management.png + +This form is a table with three columns: + +#. The first column displays the information for the reference item, +#. The second column displays the information proposed by the submitter, +#. The third column is a list of checkboxes. For each row checked, after the + validation, the value of the modified item will replace the value of the + reference item. + +.. Note:: + To reject all modifications validate the form with no checkbox checked. diff --git a/docs/en/conf.py b/docs/en/conf.py new file mode 100644 index 0000000..7b92da9 --- /dev/null +++ b/docs/en/conf.py @@ -0,0 +1,216 @@ +# -*- coding: utf-8 -*- +# +# Chimère documentation build configuration file, created by +# sphinx-quickstart on Wed Feb 15 00:42:28 2012. +# +# 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, 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('.')) + +# -- 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 = [] + +# 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'Chimère' +copyright = u'2012, Étienne Loks' + +# 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 = '2.0' +# The full version, including alpha/beta/rc tags. +release = '2.0' + +# 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 = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# 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'] + +# 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 = 'Chimredoc' + + +# -- 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, documentclass [howto/manual]). +latex_documents = [ + ('index', 'Chimre.tex', u'Chimère Documentation', + u'Étienne Loks', '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 + +# 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_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', 'chimre', u'Chimère Documentation', + [u'Étienne Loks'], 1) +] diff --git a/docs/en/configuration.rst b/docs/en/configuration.rst new file mode 100644 index 0000000..e5870bb --- /dev/null +++ b/docs/en/configuration.rst @@ -0,0 +1,187 @@ +.. -*- coding: utf-8 -*- + +============= +Configuration +============= + +:Author: Étienne Loks +:date: 2012-10-08 +:Copyright: CC-BY 3.0 + +This document presents the first steps to configure your Chimère. +It has been updated for version 2.0.0. + +Your session has to be initialised with these environment variables in +the Command Line Interface:: + + CHIMERE_PATH=/srv/chimere # change with your installation path + CHIMERE_LOCALNAME=mychimere # change with your local project name + CHIMERE_APP_PATH=$CHIMERE_PATH/$CHIMERE_LOCALNAME + + +Once the application installed, there are a few simple steps to follow to +configure *your* Chimère. + +Most of these steps are done in the web administration pages. + +If you are not familiar with *Django-like* administration pages you can look +at the first paragraph of :ref:`administration` where it is presented. + +To access these pages you have to identify with an account with *staff* and +*superuser* status. + +A *superuser* account is created at the initialization of the database. + +Configuring the Sites framework +------------------------------- + +*Sites* framework allow you to serve the same content on different domains. +Most of you will probably use only one domain but this unique domain has to +be configured. This is done in the web administration interface in *Sites > Sites*. +You only need to change *example.com* by your domain name. If you forget to +do that, some functionalities such as RSS feeds will not work properly. + +.. _managing-areas: + +Managing areas +-------------- + +An *Area* is the base of your map. It defines: + +* a name: a human readable label for this area, +* an associated URN (*not mandatory*): the name of the area as a web ressource. + In practice, if the area is not the default area the URN is used at the end of + the default URL to access to this area. This is not mandatory but necessary + for each area that is not the default one, +* a welcome message (*not mandatory*): this message is displayed once a day per + user arriving on the map, +* an order (to sort areas), +* an availability, +* a "*default*" state. The "*default*" area is viewed by default. Only one area + can be the default: activating this state disables it on the possible other + area with a default state, +* default checked categories (*not mandatory*), +* if categories are displayed dynamically. If dynamically is set, the end user + only views categories which have items on the map section he is currently + looking at, +* categories restriction (*not mandatory*): if no restriction is set all + categories are available, +* an external CSS file (*not mandatory*): an URL to an external CSS file, +* restriction on the bounding box: if set to restricted, the end user can't pan + outside the defined bounding box. Due to technical reasons of OpenLayers, + there is at this time no restriction on the zoom, +* a map bounding box: this is the area to display when arriving on the map. If + the area is restricted it will be the bounding box that restricts the end + user. Hold the *control* key, click and drag to draw the bounding box, +* available layers (*not mandatory*: OSM Mapnik is used by default): OSM + Mapnik render, OSM MapQuest render, OSM Transport Map render, OSM CycleMap are + available by default. You can add new custom layers (cf. + :ref:`managing-layers`). + +*Areas* are customizable directly on the web administration interface in +*Chimere > Areas*. + +As there is little chance that the default area should be appropriated for you, +you'll have to set at least one default area. + +Adding many areas can be a mean to show your map in different flavors. + +Managing users +-------------- + +If you are not the only administrator/moderator of this Chimère installation +you have to create and manage account for the other users. + +You can create a new *superuser* account with the Command Line Interface (CLI):: + + ./manage.py createsuperuser + +User password can be changed with the CLI (useful if you have forgotten your +password):: + + ./manage.py changepassword username + +*Users* are customizable directly on the web administration interface in +*Auth/User*. + +To create a new account, simply click on the *Add* button near *Users*. Give a +name and a default password (the user can change it on his own later). + +Then complete the other pieces of information. + +Check the case: *Staff status* (or this user will not be able to log to the +administration website). + +If this account is a new technical administrator, check *Superuser status* (this +user must be trustworthy!). Otherwise you'll have to give permissions to this +new user. It is easier not to add permission manually but to make this user +a member of a group. + +Two types of default group are proposed: application administrator and +moderator. + +Moderator are limited to an *Area* (they only see items that are inside the +bounding box). If a moderator manages many areas you'll have to select many +groups. + +Detail of rights for default groups: + ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Item (add/modify/delete on) | Technical administrator | Application administrator | Moderator | ++=========================================+=========================+===========================+===========+ +| User | yes | no | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Group | yes | no | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Property model | yes | no | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Import | yes | no | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Layer | yes | no | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| News | yes | yes | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Area | yes | yes | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Icon | yes | yes | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Color/Color theme | yes | yes | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Category/Subcategory | yes | yes | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Point Of Interest | yes | yes | yes | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Route | yes | yes | yes | ++-----------------------------------------+-------------------------+---------------------------+-----------+ + + +Creating property models +------------------------ + +A basic installation of Chimère permits to associate a name, a category, a +description, dates, multimedia files, picture files, etc. for each geographic +item. + +You may want to add more custom fields like phone number or opening hours. For +that all you have to do is to add a new property model (*Chimere/Property +model*). + +The administration page asks you for: + +* a name, +* an order (to sort properties), +* an availability to the end user (this can be used to set hidden properties), +* a mandatory status, +* the categories the property applies to (if no categories selected it applies + to all), +* the type: text, long text, password or date. + +To make this property available it is necessary to reload your web server (the +property is cached). + +All forms are then automatically updated with this new field. + +If you don't want to allow add and modification of properties you can disable +this form by setting CHIMERE_HIDE_PROPERTYMODEL to *True* in your +*local_settings.py* file. + diff --git a/docs/en/customisation.rst b/docs/en/customisation.rst new file mode 100644 index 0000000..665e2f8 --- /dev/null +++ b/docs/en/customisation.rst @@ -0,0 +1,52 @@ +.. -*- coding: utf-8 -*- + +============= +Customisation +============= + +:Author: Étienne Loks +:date: 2012-11-28 +:Copyright: CC-BY 3.0 + +This document presents the customisation of Chimère. +It has been updated for version 2.0.0. + + +.. _managing-layers: + +Managing layers +--------------- + +There are some different layers available by default in Chimère (OSM Mapnik, OSM +Mapquest, OSM Transport map, OSM Cyclemap). You can add some extra layer using +the web administration pages of Chimère. The new layer is defined with the +appropriate `Openlayers `_ JS code. This JS code must +be a compatible Openlayers Layer instance with no ending semi-colon. For +instance defining a Bing layer can be done with this kind of code:: + + new OpenLayers.Layer.Bing({ + name: "Aerial", + key: "my-bing-API-key", + type: "Aerial"}) + + +Refer to the `Openlayers documentation API +`_ +for more details. + + +Customizing the layout and the design +------------------------------------- + +If you only want to customize the CSS, the easiest way to do it is to add a +link to an extra CSS to your *Areas* cf. :ref:`managing-areas`. + +If you want to do larger changes in the layout and the style the (well named) +example_project can be customized to fit your needs. Each template file present +in the *chimere/templates* directory can be copied in your *myproject/templates* +directory and then modified. +You only need to copy files that you want to modify. These files are in +Django template language mainly made of pure HTML with some logic. Refer to +the `Django template documentation `_ +for more details. + diff --git a/docs/en/import_export.rst b/docs/en/import_export.rst new file mode 100644 index 0000000..73a95af --- /dev/null +++ b/docs/en/import_export.rst @@ -0,0 +1,235 @@ +.. -*- coding: utf-8 -*- + +============= +Import/export +============= + +:Author: Étienne Loks +:date: 2012-11-28 +:Copyright: CC-BY 3.0 + +This document presents the import/export functionnalities of Chimère. +It has been updated for version 2.0.0. + +.. _importing: + +Importing +--------- + +In Chimère the import mechanism is based on **Import object**. These objects +are stored in database to keep trace of imports and to facilitate the +re-importation from the same source. In fact if possible the update of data from +a same type of source is managed. + +.. Note:: + The ability to do such updates depends on the existence of a unique id + for each object on your source. + +To add an **Import object** you need to go to *Chimere > Imports* then **Add**. + +After that you'll have to select your source type and then the form depends on +this source type. + +Common fields +************* + +- **Name by default**: if no name can be identified to the newly imported object + this is the name that will be used. If this field is empty the name of the + associated category will be use. +- **SRID**: Chimère will try to identify automatically the correct coordinate + system from the given source. But sometimes the information is not present or + cannot be guessed (for instance a Shapefile that uses non standard proj file). + In this case Chimère will use WGS84 by default (the classic + latitude/longitude) but it is not always correct. If you experience problems + with items localisation you should put here the `SRID + `_ associated to the coordinate system of + your source. +- **Origin**: if not null this field will be associated to each item imported in + order to easily identify where the item came from. For OSM import the source + is automatically added. +- **License**: if not null this field will be associated to each item imported in + order to easily identify the license associated to the item. For OSM import + the license is automatically added. +- **Associated subcategories (mandatory)**: The selected subcategories will be + associated to newly imported items. + + +KML import +********** + +.. image:: static/chimere_admin_import_KML.png + + +- **Web address/source file (mandatory)**: your KML could be distant or a local + file. You'll have to fill one of the two fields. +- **Filter**: if you want to import only a specific *Folder* of your KML file + put his name on this field. +- **Zipped file**: if your source is a KMLZ file (a zipped KML), check this case. + +Shapefile import +**************** + +.. image:: static/chimere_admin_import_shapefile.png + + +- **Web address/source file (mandatory)**: your Shapefile could be distant or a + local file. You'll have to fill one of the two fields. +- **Zipped file**: only zipped Shapefiles are accepted so this checkbox has to be + checked. + +GeoRSS import +************* + +Simple GeoRSS and W3C GeoRSS are managed. + +.. image:: static/chimere_admin_import_georss.png + +- **Web address (mandatory)**: only distant GeoRSS are managed. + +CSV import +********** + +The format of the CSV file (number and order of columns) managed by Chimère +varies depending on the properties you have added on your Chimère instance. +So we recommend you to first do an export of some items in CSV with Chimère. +The CSV format of the exported file will meet Chimère requirements. + +By the way because of the geometry of the item this format is not very +convenient to add new content but could be handy to update informations. + +.. Warning:: + If you mean to update existing data by this import, unless you know how to + edit WKT do *not* modify the geometry column. + +.. image:: static/chimere_admin_import_CSV.png + +- **Web address/source file (mandatory)**: your CSV file could be distant or a + local file. You'll have to fill one of the two fields. + +.. _osm-import: + +OpenStreetMap import +******************** + +.. image:: static/chimere_admin_import_OSM.png + +To import from OSM Chimère use the XAPI API of OSM. + +- **Web address (mandatory)**: XAPI url used to import data. This field should + be filled with a default address. By default the MapQuest server is used as it + seems to be the more robust. If you experience problems with OSM import, check + the availability of the XAPI server used and eventually change it. +- **Filter area (mandatory)**: draw the bounding box you want to use for your + OSM import. +- **Filter type (mandatory)**: choose if you want to import way or nodes. +- **Filter tag (mandatory)**: choose the OSM key/value couple used to filter OSM + data. A link to the `OSM Map features page + `_ is provided to help you + find appropriate values. +- **Refresh button**: this button convert your choices to appropriate XAPI args. + You have to hit this button before validating the form. + +Importing +********* + +Once your new import item created, select it in the import object list, choose +the **Import** action and validate. + +The import should be processing normally. If not, an explicit error message +should be printed in the state column of your import. + +You can also launch imports with the CLI (ideal for crontab jobs). In the +project directory you only need to launch the command:: + + ./manage.py chimere_import + +- *import_id* is the import ID + +If you launch the command without *import_id* the list of imports available is +presented and you can choose one. + +Managing imported data +********************** + +All new imported items have the state **Imported**. To make them available on +the map you'll have to validate them. If you don't want some items to be visible +on the map, instead of deleting them it is recommended to set them to the state +**Disabled**. So on the next update from the source, rather than appear as new +items they remain disabled. + +.. Warning:: + Be careful with duplicates between your existing data and imported data. This + is particularly important if you want to export your data to OSM. + +Exporting +--------- + +Export to CSV/KML/Shapefile +*************************** + +Directly from the :ref:`geographic items list ` you +can export to the chosen format. All you have to do is to select the desired +items, choose the appropriate action in the action list and validate. + +You can also launch exports with the CLI (ideal for crontab jobs). In the +project directory you only need to launch the command:: + + ./manage.py chimere_export \ + + +- *subcategory_id* is the ID of the chosen subcategory +- *CSV|KML|SHP* is the chosen format +- *marker|route* is to get marker or route +- *filename* is the output filename + +If you launch the command without arguments you will be prompted for the choice +to make for your export. + + +Export to OSM +************* + +.. Warning:: + If you are not sure of what you are doing with OSM export: don't do it! It is + really important to not mess with others' data. + +.. Note:: + Only export of OSM nodes are managed. + +OSM export is not that easily managed. First (if not yet done) you'll have to +define an import (:ref:`see above ` for details). This will enable +to determine: + +- the area concerned by your export. +- the key/value tag to append to your new/updated items. +- the subcategories concerned by your export. If you think that some items in + these subcategories should not be in OSM database (because there are not + relevant or because of license issues) beforehand mark them as **Not for OSM** + in the *import fields* of the :ref:`geographic items forms + `. + + +The OSM export in Chimère is designed to be the more preservative possible in +regards to OSM database. That's why before any export an import is done. If +the new import has updated data, these new data will overload data in your +Chimère (if you don't want that: don't do re-imports so dont do exports). All +pending imported items should have been treated before doing an export. + +To launch an export select the appropriate *Import* object in the imports list. +Then select the **Export to OSM** action and validate. +Then you'll be asked for your OSM username and password and the API you want to +use. If you regularly use Chimère to do export, it is recommended to create an +OSM specific account for that. +The test API is available to make export test. If you want to use the test +API you'll have to create a specific account on the test platform. + +.. Warning:: + The data on the test platform are not synced with the main platform. You won't + have the same data than the ones you got with XAPI. + +Once all this field filled, you can (finally!) launch the export. + +When exporting tags are automatically added/updated: + +- *name*: get from the item name in Chimère. +- *source*: to identify Chimère as a source. diff --git a/docs/en/index.rst b/docs/en/index.rst new file mode 100644 index 0000000..ee1dd6f --- /dev/null +++ b/docs/en/index.rst @@ -0,0 +1,17 @@ +.. Chimère documentation master file, created by + sphinx-quickstart on Wed Feb 15 00:42:28 2012. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Chimère's documentation! +=================================== + +.. toctree:: + :maxdepth: 2 + + install + upgrade + configuration + administration + import_export + customisation diff --git a/docs/en/install.rst b/docs/en/install.rst new file mode 100644 index 0000000..ea27efc --- /dev/null +++ b/docs/en/install.rst @@ -0,0 +1,290 @@ +.. -*- coding: utf-8 -*- + +============ +Installation +============ + +:Author: Étienne Loks +:date: 2012-11-28 +:Copyright: CC-BY 3.0 + +This document presents the installation of Chimère. +It has been updated for version 2.0.0. + +Prerequisites +************* + + - `Apache `_ version 2.x + - `Python `_ versions 2.6 or 2.7 + - `Django `_ >= version 1.4 + - `South `_ + - `Postgres `_ >= version 8.x + - `Gettext `_ + - `Psycopg2 `_ + - `Python Imaging Library `_ + - `Pyexiv2 `_ + - `Beautiful Soup `_ + - python-simplejson + - python-gdal + - `Lxml `_ + - `Jquery `_ version 1.7.1 or better + - `Jquery-ui `_ + - `Universal Feed Parser `_ + +geodjango is a part of django since version 1.0 but it has some specific +(geographically related) additional dependencies: + + - `geos `_ 3.0.x + - `proj.4 `_ 4.4 to 4.6 + - `postgis `_ versions 1.2.1 or 1.3.x + - `gdal `_ + + +Optionaly (but recommanded): + + - `tinymce `_ + - `gpsbabel `_ + - django-celery if you want to manage large imports + + +The simpliest way to obtain these packages is to get them from your favorite +Linux distribution repositories. For instance on Debian Wheezy:: + + apt-get install apache2 python python-django python-django-south \ + postgresql-9.1 gettext python-psycopg2 python-imaging \ + python-pyexiv2 python-beautifulsoup python-simplejson python-gdal \ + python-lxml libjs-jquery libjs-jquery-ui python-feedparser \ + libgeos-3.3.3 proj-bin postgresql-9.1-postgis gdal-bin \ + tinymce gpsbabel python-django-celery javascript-common + + +On Debian Squeeze (you need to activate backports):: + + apt-get install -t squeeze-backports python-django libjs-jquery + + apt-get install apache2 python python-django python-django-south \ + postgresql-8.4 gettext python-psycopg2 python-imaging \ + python-pyexiv2 python-beautifulsoup python-simplejson python-gdal \ + python-lxml libjs-jquery libjs-jquery-ui python-feedparser \ + libgeos-3.2.0 proj-bin postgresql-8.4-postgis gdal-bin \ + tinymce gpsbabel javascript-common + +The package *python-django-celery* doesn't exist for Debian Squeeze. + +If these packages do not exist in your distribution's repository, please refer +to the applications' websites. + +Database configuration +********************** + +Now that postgres and postgis are installed, you need to create a new user for +Chimère:: + + su postgres + createuser --echo --adduser --createdb --encrypted --pwprompt chimere-user + +Then, you have to create the database and initialize the geographic types (adapt +the paths accordingly to your needs):: + + PG_VERSION=9.1 # 8.4 for debian Squeeze + createdb --echo --owner chimere-user --encoding UNICODE chimere "My Chimère database" + createlang plpgsql chimere # only necessary on Debian Squeeze + psql -d chimere -f /usr/share/postgresql/$PG_VERSION/contrib/postgis-1.5/postgis.sql + psql -d chimere -f /usr/share/postgresql/$PG_VERSION/contrib/postgis-1.5/spatial_ref_sys.sql + +Installing the sources +********************** + +.. Note:: + If you are considering to contribute on Chimère get the Git master. + +Choose a path to install your Chimère:: + + INSTALL_PATH=/var/local/django + mkdir $INSTALL_PATH + +From an archive ++++++++++++++++ + +The last "stable" version is available in this `directory `_. +Take care of getting the last version in the desired X.Y branch (for instance +the last version for the 1.0 branch is version 1.0.2).:: + + wget http://www.peacefrogs.net/download/chimere -q -O -| html2text + (...) + [[ ]] chimere-1.0.0.tar.bz2 17-Nov-2010 16:51 53K + [[ ]] chimere-1.0.1.tar.bz2 17-Nov-2010 16:51 53K + [[ ]] chimere-1.0.2.tar.bz2 17-Nov-2010 16:51 53K + (...) + + wget http://www.peacefrogs.net/download/chimere/chimere-1.0.2.tar.bz2 + +Download, unpack and move the files in an apache user (www-data for Debian) +readable directory:: + + cd $INSTALL_PATH + tar xvjf chimere-last.tar.bz2 + chown -R myusername:www-data chimere + +From the Git repository ++++++++++++++++++++++++ + +Another solution is to get it from the Git repository:: + + cd $INSTALL_PATH + git clone git://www.peacefrogs.net/git/chimere + cd chimere + git tag -l # list tagged versions + git checkout v2.0 # checkout the desired version + + +Creating a custom project template +********************************** + +There, a default project is provided (*example_project*). Copy and modify +it (or get another project based on Chimère):: + + cd $INSTALL_PATH/chimere + cp -ra example_project mychimere_project + +Your project name is used for the name of the Python package of your template. +As a Python package it should follow the rule of Python variable name: +it must contain at least one letter and can have a string of numbers, letters and +underscores ("_") to any length. Don't use accentuated letters. Don't begin the +name by "_" because it has special significance in Python. + +In your Chimère application directory create *local_settings.py* to fit to your +configuration. +A base template is provided (*local_settings.py.example*) and short descriptions +of the more relevant fields are given below (at least check them). Most of +these settings are initialized in *settings.py*. :: + + cd $INSTALL_PATH/chimere/mychimere_project + cp local_settings.py.sample local_settings.py + vim local_settings.py + +:Fields: + + * DATABASES: parameters for the database + * PROJECT_NAME: name of the project + * SECRET_KEY: a secret key for a particular Django installation. This is + used to provide cryptographic signing, and should be set to a unique, + unpredictable value. **Change it!** + * ROOT_URLCONF: url configuration for your project something like: + 'mychimere_project.urls' + * EMAIL_HOST: smtp of an email server to send emails + * TINYMCE_URL: url to tinymce path (default is appropriate for a Debian + installation with tinymce package installed) + * JQUERY_JS_URLS: list of jquery and jquery-ui javascript urls (default is + appropriate for a Debian installation with libjs-jquery libjs-jquery-ui + packages installed) + * JQUERY_CSS_URLS: list of jquery and jquery-ui CSS urls (default is + appropriate for a Debian installation with libjs-jquery libjs-jquery-ui + packages installed) + * GPSBABEL: path to gpsbabel (default is appropriate for a Debian + installation with gpsbabel package installed) + * TIME_ZONE: local time zone for this installation + * LANGUAGE_CODE: language code for this installation + +Manage media path permission:: + + cd $INSTALL_PATH/chimere/mychimere_project + chown -R user:www-data media + chmod -R g+w media + +Create log file:: + + mkdir /var/log/django + touch /var/log/django/chimere.log + chown -R root:www-data /var/log/django/ + chmod -R g+w /var/log/django/ + +Regroup static files in one path:: + + cd $INSTALL_PATH/chimere/mychimere_project + ./manage.py collectstatic + +Compiling languages +******************* + +If your language is available in the directory *chimere/locale/*, you will just +need to get it compiled. This can be done with the following command (here, +**fr** stands for French, replace it with the appropriate language code):: + + cd $INSTALL_PATH/chimere/chimere/ + django-admin compilemessages -l fr + +If your language is not available, feel free to create the default po file and +to submit it, contributions are well appreciated. Procedure is as follows: + +You first need to create the default po file (of course, replace **fr** +according to the language you choose to create):: + + django-admin makemessages -l fr + +There should now be a *django.po* file in *locale/fr/LC_MESSAGES*. Complete it +with your translation. + +Now that the translation file is completed, just compile it the same way you +would have if the language file was already available. + +Database initialisation +*********************** + +Create the appropriate tables (still being in your Chimère project directory):: + + cd $INSTALL_PATH/chimere/mychimere_project + ./manage.py syncdb + +You will be prompted for the creation of an administrator account +(administration can be found at: http://where_is_chimere/admin/). Then you have +to create tables managed with Django-South:: + + ./manage.py migrate + +The database is set, congratulations! + +If you want to populate your installation with default data (don't do this on +an already populated instance!):: + + ./manage.py loaddata ../chimere/fixtures/default_data.json + +Webserver configuration +*********************** + +Apache configuration with mod_wsgi +++++++++++++++++++++++++++++++++++ + +Install *mod_wsgi* for Apache:: + + apt-get install libapache2-mod-wsgi + + +Create and edit a configuration for Chimère:: + + cp $INSTALL_PATH/chimere/apache/django.wsgi \ + $INSTALL_PATH/chimere/apache/mydjango.wsgi + vim $INSTALL_PATH/chimere/apache/mydjango.wsgi + cp $INSTALL_PATH/chimere/apache/apache-wsgi.conf \ + /etc/apache2/sites-available/chimere + vim /etc/apache2/sites-available/chimere + # create log dir + mkdir /var/log/apache2/chimere/ + chown www-data /var/log/apache2/chimere/ + +Adapt the files *mydjango.wsgi* (with the correct sys path and the correct +module) and Apache *chimere* (with the correct servername and correct paths). + +To activate the website, reload apache:: + + a2ensite chimere + /etc/init.d/apache2 reload + +If you encounter problem with the upload of files with Unicode chars in their +names, activate the appropriate locale in Apache. On a Debian server with UTF-8 +as default encoding, in the file */etc/apache2/envvars* uncomment the following +line:: + + . /etc/default/locale + + diff --git a/docs/en/static/chimere_admin_00.png b/docs/en/static/chimere_admin_00.png new file mode 100644 index 0000000..374c6b6 Binary files /dev/null and b/docs/en/static/chimere_admin_00.png differ diff --git a/docs/en/static/chimere_admin_01.png b/docs/en/static/chimere_admin_01.png new file mode 100644 index 0000000..0db7f4d Binary files /dev/null and b/docs/en/static/chimere_admin_01.png differ diff --git a/docs/en/static/chimere_admin_02.png b/docs/en/static/chimere_admin_02.png new file mode 100644 index 0000000..d0fd6fe Binary files /dev/null and b/docs/en/static/chimere_admin_02.png differ diff --git a/docs/en/static/chimere_admin_03.png b/docs/en/static/chimere_admin_03.png new file mode 100644 index 0000000..e815500 Binary files /dev/null and b/docs/en/static/chimere_admin_03.png differ diff --git a/docs/en/static/chimere_admin_import_CSV.png b/docs/en/static/chimere_admin_import_CSV.png new file mode 100644 index 0000000..e67a37b Binary files /dev/null and b/docs/en/static/chimere_admin_import_CSV.png differ diff --git a/docs/en/static/chimere_admin_import_KML.png b/docs/en/static/chimere_admin_import_KML.png new file mode 100644 index 0000000..b48d69a Binary files /dev/null and b/docs/en/static/chimere_admin_import_KML.png differ diff --git a/docs/en/static/chimere_admin_import_OSM.png b/docs/en/static/chimere_admin_import_OSM.png new file mode 100644 index 0000000..a599348 Binary files /dev/null and b/docs/en/static/chimere_admin_import_OSM.png differ diff --git a/docs/en/static/chimere_admin_import_georss.png b/docs/en/static/chimere_admin_import_georss.png new file mode 100644 index 0000000..5278652 Binary files /dev/null and b/docs/en/static/chimere_admin_import_georss.png differ diff --git a/docs/en/static/chimere_admin_import_shapefile.png b/docs/en/static/chimere_admin_import_shapefile.png new file mode 100644 index 0000000..ce612be Binary files /dev/null and b/docs/en/static/chimere_admin_import_shapefile.png differ diff --git a/docs/en/static/chimere_admin_modified_management.png b/docs/en/static/chimere_admin_modified_management.png new file mode 100644 index 0000000..84e069e Binary files /dev/null and b/docs/en/static/chimere_admin_modified_management.png differ diff --git a/docs/en/static/chimere_admin_modify_item.png b/docs/en/static/chimere_admin_modify_item.png new file mode 100644 index 0000000..861ea20 Binary files /dev/null and b/docs/en/static/chimere_admin_modify_item.png differ diff --git a/docs/en/upgrade.rst b/docs/en/upgrade.rst new file mode 100644 index 0000000..d44ae02 --- /dev/null +++ b/docs/en/upgrade.rst @@ -0,0 +1,311 @@ +.. -*- coding: utf-8 -*- + +======= +Upgrade +======= + +:Author: Étienne Loks +:date: 2012-10-08 +:Copyright: CC-BY 3.0 + +This document presents the upgrade of Chimère. +It has been updated for version 2.0.0. + +.. Warning:: + Before any upgrade backup the database and all your installation files + (specially if you have made changes to them). + +The process for migration requires a basic knowledge of Git and Linux CLI. It is +*not* an easy process. A work is currently done to easy the upgrade in later +versions (>2.0) of Chimère. + +If several versions have been published, you should repeat all upgrading steps. +For instance to upgrade from v1.1 to v2.0 you should first upgrade to v1.2 then +to v2.0. The only optional step is the integration of your customisations. + +The current stable version is 2.0. + +.. Note:: + If you are considering to contribute on Chimère get the Git master. + +The instructions are given for Debian Squeeze and Debian Wheezy. + + +Getting new versions of dependencies +------------------------------------ + +Version 1.1 -> 1.2 +****************** + +.. code-block:: bash + + apt-get install python-lxml libjs-jquery gpsbabel python-gdal + +Version 1.2 -> 2.0 +****************** + +Debian Squeeze +++++++++++++++ +Activate the backports: http://backports-master.debian.org/Instructions/ +Then install the new dependencies:: + + apt-get install -t squeeze-backports python-django python-django-south \ + python-simplejson libjs-jquery-ui python-pyexiv2 \ + python-feedparser javascript-common libjs-jquery + +Debian Wheezy ++++++++++++++ + +.. code-block:: bash + + apt-get install python-django-south python-simplejson libjs-jquery-ui \ + python-pyexiv2 python-feedparser javascript-common + +If you are planning to do major import consider the install of `Celery +`_. + +.. code-block:: bash + + apt-get install python-django-celery python-kombu + +Getting the new sources +----------------------- + +First of all you have to get the new version of the source code. +For the upgrade process, the source code has to be from the Git +repository. + +To simplify further instructions, some environment variables are +initialized. + +.. code-block:: bash + + CHIMERE_PATH=/srv/chimere + CHIMERE_TAG=v1.2.0 # version 1.1 -> 1.2 + CHIMERE_TAG=v2.0-RC3 # version 1.2 -> 2.0 + CHIMERE_TAG=master # version 2.0 -> master + CHIMERE_LOCALNAME=mychimere + +Your local name is used for the name of your local Git branch and the Python +package. As a Python package it should follow the rule of Python variable name: +it must be at least one letter and can have a string of numbers, letters and +underscores ("_") to any length. Don't begin the name by "_" because it has special +significance in Python. + +From a previous Git installation +******************************** + +.. code-block:: bash + + cd $CHIMERE_PATH + git checkout -b $CHIMERE_LOCALNAME # only if you haven't created yet a local branch + git stash # if you have uncommited changes + git checkout master + git pull + git checkout $CHIMERE_LOCALNAME + git rebase $CHIMERE_TAG + +From a previous tarball installation +************************************ + +First remove your old installation and get the Git version: + +.. code-block:: bash + + cd $CHIMERE_PATH + cd .. + rm -rf $CHIMERE_PATH + git clone git://www.peacefrogs.net/git/chimere + cd chimere + git checkout $CHIMERE_TAG + git checkout -b $CHIMERE_LOCALNAME + + +Update basic settings +********************* + +Version 1.1 -> 1.2 +++++++++++++++++++ + +.. code-block:: bash + + CHIMERE_APP_PATH=$CHIMERE_PATH/chimere + vim $CHIMERE_APP_PATH/settings.py + +Add the following lines (adapted for your jquery and gpsbabel installation): + +.. code-block:: python + + JQUERY_URL = SERVER_URL + 'jquery/jquery-1.4.4.min.js' + GPSBABEL = '/usr/bin/gpsbabel' + # simplify with an error of 5 meters + GPSBABEL_OPTIONS = 'simplify,crosstrack,error=0.005k' + +Version 1.2 -> 2.0 +++++++++++++++++++ + +Project template +................ +Create a new project template: + +.. code-block:: bash + + cd $CHIMERE_PATH + cp -ra $CHIMERE_PATH/example_project $CHIMERE_LOCALNAME + CHIMERE_APP_PATH=$CHIMERE_PATH/$CHIMERE_LOCALNAME + +local_settings +.............. +A *local_settings* file is now used. + +.. code-block:: bash + + cd $CHIMERE_APP_PATH + cp local_settings.py.sample local_settings.py + vim local_settings.py + +Report your old settings from *settings.py* to *local_settings.py* (at least the +database configuration). +The setting *ROOT_URLCONF* must be set to **value_of_your_localname.urls**. + +logs +.... +Logging is now enabled by default in the file */var/log/django/chimere.log*. + +.. code-block:: bash + + mkdir /var/log/django + touch /var/log/django/chimere.log + chown www-data -R /var/log/django + +Static files +............ + +Now static files are managed with *django.contrib.staticfiles*. + +.. code-block:: bash + + cd $CHIMERE_APP_PATH + ./manage.py collectstatic + +Move old static files to the new static directory: + +.. code-block:: bash + + cp -ra $CHIMERE_PATH/chimere/static/* $CHIMERE_APP_PATH/static/ + cp -ra $CHIMERE_PATH/chimere/static/icons/* $CHIMERE_APP_PATH/media/icons/ + cp -ra $CHIMERE_PATH/chimere/static/upload $CHIMERE_APP_PATH/media/ + +Webserver configuration +....................... +If you are using Apache and WSGI to serve your Chimère, change your WSGI +configuration file to point to the correct settings: +**value_of_your_localname.settings**. + +Change your webserver directive to point to the correct static directory from +**your_chimere_path/chimere/static** to +**your_chimere_path/your_local_name/static**. + +Version 2.0 -> master ++++++++++++++++++++++ + +Update settings and static files. + +.. code-block:: bash + + cp $CHIMERE_PATH/example_project/settings.py $CHIMERE_LOCALNAME + ./manage.py collectstatic + +Migrate database +---------------- + +Version 1.1 -> 1.2 +****************** + +Migration scripts test your installation before making changes so you probably +won't have any lost but by precaution before running these scripts don't forget +to backup your database. +You can also make a copy of your current database into a new database and make +the new installation to this new database. + +The gdal binding for Python is necessary to run the upgrade scripts (available +in the python-gdal package in Debian). + +If you run the migration scripts in a production environnement stop the old +instance of Chimère before executing the migration script. + +In *settings.py* verify that **chimere.scripts** is in the *INSTALLED_APPS*. + +After that in the Chimère directory just execute the script. + +.. code-block:: bash + + cd $CHIMERE_APP_PATH + python ./scripts/upgrade.py + +Version 1.2 -> 2.0 +****************** + +Django South is now used to manage database migrations. + +.. code-block:: bash + + cd $CHIMERE_APP_PATH + ./manage.py syncdb + ./manage.py migrate chimere 0001 --fake # fake the database initialisation + ./manage.py migrate chimere + +A description field is now available for markers. If you would like to move +values of an old *Property model* to this new field, a script is available. + +.. code-block:: bash + + cd $CHIMERE_APP_PATH + ../chimere/scripts/migrate_properties.py + # follow the instructions + +Version 2.0 -> master +********************* + +.. code-block:: bash + + cd $CHIMERE_APP_PATH + ./manage.py syncdb + ./manage.py migrate chimere + +Update translations +------------------- + +Version 1.1 -> 1.2 +****************** + +.. code-block:: bash + + cd $CHIMERE_APP_PATH + ./manage.py compilemessages + +Version 1.2 -> 2.0 -> master +**************************** + +.. code-block:: bash + + cd $CHIMERE_PATH/chimere + django-admin compilemessages + +Forcing the refresh of visitor's web browser cache +-------------------------------------------------- + +Major changes in the javascript has been done between versions, many of your +users could experience problems. There are many tricks to force the refresh +of their cache. One of them is to change the location of statics files. To do +that edit your local_settings.py and change:: + + STATIC_URL = '/static/' + +to:: + + STATIC_URL = '/static/v2.0.0/' + +Then change the webserver directive to point to your new path. +Restart the web server to apply this changes. + diff --git a/docs/fr/Makefile b/docs/fr/Makefile new file mode 100644 index 0000000..fcccf30 --- /dev/null +++ b/docs/fr/Makefile @@ -0,0 +1,130 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +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 $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +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 " text to make text files" + @echo " man to make manual pages" + @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 $(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/Chimre.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Chimre.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/Chimre" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Chimre" + @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." + +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." + +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." diff --git a/docs/fr/administration.rst b/docs/fr/administration.rst index d4fb145..cdf79b5 100644 --- a/docs/fr/administration.rst +++ b/docs/fr/administration.rst @@ -26,7 +26,7 @@ Identification Tout d'abord vous avez à vous identifier avec l'identifiant et le mot de passe fourni. -.. image:: _static/chimere_admin_00.png +.. image:: static/chimere_admin_00.png Page principale @@ -36,7 +36,7 @@ Une fois identifié, vous avez accès à la page principale d'administration. Cela s'affiche ainsi : -.. image:: _static/chimere_admin_01.png +.. image:: static/chimere_admin_01.png #. lien vers cette **Documentation**, vers le formulaire de **Changement de mot de passe** et la déconnexion ; @@ -53,7 +53,7 @@ Cela s'affiche ainsi : Liste des éléments ****************** -.. image:: _static/chimere_admin_02.png +.. image:: static/chimere_admin_02.png #. chemin dans le site d'administration. C'est un raccourci pratique pour revenir à la page principale. @@ -73,7 +73,7 @@ Liste des éléments Formulaire des éléments *********************** -.. image:: _static/chimere_admin_03.png +.. image:: static/chimere_admin_03.png #. les champs pour l'élément sélectionné (ou vide si c'est un nouvel élément) sont affichés dans ce formulaire. Parfois certains champs sont en lecture @@ -172,7 +172,7 @@ Il y a un certain nombre d'action disponible. Pour modifier un élément, classiquement, vous cliquez sur son nom pour accéder ensuite à un formulaire pour modifier librement l'élément. -.. image:: _static/chimere_admin_modify_item.png +.. image:: static/chimere_admin_modify_item.png Sur ce formulaire il y a tous les éléments disponibles à l'utilisateur plus quelques champs supplémentaires. @@ -217,7 +217,7 @@ Un formulaire spécifique a été développé pour faciliter le traitement de ce Vous pouvez accéder à ce formulaire spécifique avec l'action *Gérer les éléments modifiés*. -.. image:: _static/chimere_admin_modified_management.png +.. image:: static/chimere_admin_modified_management.png Ce formulaire est un tableau à 3 colonnes. diff --git a/docs/fr/conf.py b/docs/fr/conf.py new file mode 100644 index 0000000..6a0724e --- /dev/null +++ b/docs/fr/conf.py @@ -0,0 +1,216 @@ +# -*- coding: utf-8 -*- +# +# Chimère documentation build configuration file, created by +# sphinx-quickstart on Wed Feb 15 00:42:28 2012. +# +# 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, 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('.')) + +# -- 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 = [] + +# 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'Chimère' +copyright = u'2012, Étienne Loks' + +# 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 = '2.0' +# The full version, including alpha/beta/rc tags. +release = '2.0' + +# 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 = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# 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'] + +# 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 = 'Chimredoc' + + +# -- 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, documentclass [howto/manual]). +latex_documents = [ + ('index', 'Chimre.tex', u'Documentation de Chimère', + u'Étienne Loks', '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 + +# 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_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', 'chimere', u'Chimère Documentation', + [u'Étienne Loks'], 1) +] diff --git a/docs/fr/import_export.rst b/docs/fr/import_export.rst index b63f874..11ffaa3 100644 --- a/docs/fr/import_export.rst +++ b/docs/fr/import_export.rst @@ -58,7 +58,7 @@ Champs communs à tous les types de source Import KML ********** -.. image:: _static/chimere_admin_import_KML.png +.. image:: static/chimere_admin_import_KML.png - **Adresse Web/fichier source (obligatoire)** : votre fichier KML peut être @@ -71,7 +71,7 @@ Import KML Import Shapefile **************** -.. image:: _static/chimere_admin_import_shapefile.png +.. image:: static/chimere_admin_import_shapefile.png - **Adresse Web/fichier source (obligatoire)** : votre fichier Shapefile peut @@ -84,7 +84,7 @@ Import GeoRSS Simple GeoRSS et W3C GeoRSS sont gérés. -.. image:: _static/chimere_admin_import_georss.png +.. image:: static/chimere_admin_import_georss.png - **Adresse Web (obligatoire)**: seul les flux GeoRSS distant sont gérés. @@ -108,7 +108,7 @@ mises à jour d'information. moins que vous sachiez éditer du WKT ne modifiez **pas** la colonne qui concerne la géométrie de l'élément. -.. image:: _static/chimere_admin_import_CSV.png +.. image:: static/chimere_admin_import_CSV.png - **Adresse Web/fichier source (obligatoire)** : votre fichier CSV peut être distant ou local. Vous avez à remplir un des deux champs. @@ -118,7 +118,7 @@ mises à jour d'information. Import OpenStreetMap ******************** -.. image:: _static/chimere_admin_import_OSM.png +.. image:: static/chimere_admin_import_OSM.png Pour importer depuis OSM, Chimère utilise l'API XAPI d'OSM. diff --git a/docs/fr/static/chimere_admin_00.png b/docs/fr/static/chimere_admin_00.png new file mode 100644 index 0000000..374c6b6 Binary files /dev/null and b/docs/fr/static/chimere_admin_00.png differ diff --git a/docs/fr/static/chimere_admin_01.png b/docs/fr/static/chimere_admin_01.png new file mode 100644 index 0000000..0db7f4d Binary files /dev/null and b/docs/fr/static/chimere_admin_01.png differ diff --git a/docs/fr/static/chimere_admin_02.png b/docs/fr/static/chimere_admin_02.png new file mode 100644 index 0000000..d0fd6fe Binary files /dev/null and b/docs/fr/static/chimere_admin_02.png differ diff --git a/docs/fr/static/chimere_admin_03.png b/docs/fr/static/chimere_admin_03.png new file mode 100644 index 0000000..e815500 Binary files /dev/null and b/docs/fr/static/chimere_admin_03.png differ diff --git a/docs/fr/static/chimere_admin_import_CSV.png b/docs/fr/static/chimere_admin_import_CSV.png new file mode 100644 index 0000000..e67a37b Binary files /dev/null and b/docs/fr/static/chimere_admin_import_CSV.png differ diff --git a/docs/fr/static/chimere_admin_import_KML.png b/docs/fr/static/chimere_admin_import_KML.png new file mode 100644 index 0000000..b48d69a Binary files /dev/null and b/docs/fr/static/chimere_admin_import_KML.png differ diff --git a/docs/fr/static/chimere_admin_import_OSM.png b/docs/fr/static/chimere_admin_import_OSM.png new file mode 100644 index 0000000..a599348 Binary files /dev/null and b/docs/fr/static/chimere_admin_import_OSM.png differ diff --git a/docs/fr/static/chimere_admin_import_georss.png b/docs/fr/static/chimere_admin_import_georss.png new file mode 100644 index 0000000..5278652 Binary files /dev/null and b/docs/fr/static/chimere_admin_import_georss.png differ diff --git a/docs/fr/static/chimere_admin_import_shapefile.png b/docs/fr/static/chimere_admin_import_shapefile.png new file mode 100644 index 0000000..ce612be Binary files /dev/null and b/docs/fr/static/chimere_admin_import_shapefile.png differ diff --git a/docs/fr/static/chimere_admin_modified_management.png b/docs/fr/static/chimere_admin_modified_management.png new file mode 100644 index 0000000..84e069e Binary files /dev/null and b/docs/fr/static/chimere_admin_modified_management.png differ diff --git a/docs/fr/static/chimere_admin_modify_item.png b/docs/fr/static/chimere_admin_modify_item.png new file mode 100644 index 0000000..861ea20 Binary files /dev/null and b/docs/fr/static/chimere_admin_modify_item.png differ diff --git a/docs/import_export.rst b/docs/import_export.rst deleted file mode 100644 index 3574a66..0000000 --- a/docs/import_export.rst +++ /dev/null @@ -1,235 +0,0 @@ -.. -*- coding: utf-8 -*- - -============= -Import/export -============= - -:Author: Étienne Loks -:date: 2012-11-28 -:Copyright: CC-BY 3.0 - -This document presents the import/export functionnalities of Chimère. -It has been updated for version 2.0.0. - -.. _importing: - -Importing ---------- - -In Chimère the import mechanism is based on **Import object**. These objects -are stored in database to keep trace of imports and to facilitate the -re-importation from the same source. In fact if possible the update of data from -a same type of source is managed. - -.. Note:: - The ability to do such updates depends on the existence of a unique id - for each object on your source. - -To add an **Import object** you need to go to *Chimere > Imports* then **Add**. - -After that you'll have to select your source type and then the form depends on -this source type. - -Common fields -************* - -- **Name by default**: if no name can be identified to the newly imported object - this is the name that will be used. If this field is empty the name of the - associated category will be use. -- **SRID**: Chimère will try to identify automatically the correct coordinate - system from the given source. But sometimes the information is not present or - cannot be guessed (for instance a Shapefile that uses non standard proj file). - In this case Chimère will use WGS84 by default (the classic - latitude/longitude) but it is not always correct. If you experience problems - with items localisation you should put here the `SRID - `_ associated to the coordinate system of - your source. -- **Origin**: if not null this field will be associated to each item imported in - order to easily identify where the item came from. For OSM import the source - is automatically added. -- **License**: if not null this field will be associated to each item imported in - order to easily identify the license associated to the item. For OSM import - the license is automatically added. -- **Associated subcategories (mandatory)**: The selected subcategories will be - associated to newly imported items. - - -KML import -********** - -.. image:: _static/chimere_admin_import_KML.png - - -- **Web address/source file (mandatory)**: your KML could be distant or a local - file. You'll have to fill one of the two fields. -- **Filter**: if you want to import only a specific *Folder* of your KML file - put his name on this field. -- **Zipped file**: if your source is a KMLZ file (a zipped KML), check this case. - -Shapefile import -**************** - -.. image:: _static/chimere_admin_import_shapefile.png - - -- **Web address/source file (mandatory)**: your Shapefile could be distant or a - local file. You'll have to fill one of the two fields. -- **Zipped file**: only zipped Shapefiles are accepted so this checkbox has to be - checked. - -GeoRSS import -************* - -Simple GeoRSS and W3C GeoRSS are managed. - -.. image:: _static/chimere_admin_import_georss.png - -- **Web address (mandatory)**: only distant GeoRSS are managed. - -CSV import -********** - -The format of the CSV file (number and order of columns) managed by Chimère -varies depending on the properties you have added on your Chimère instance. -So we recommend you to first do an export of some items in CSV with Chimère. -The CSV format of the exported file will meet Chimère requirements. - -By the way because of the geometry of the item this format is not very -convenient to add new content but could be handy to update informations. - -.. Warning:: - If you mean to update existing data by this import, unless you know how to - edit WKT do *not* modify the geometry column. - -.. image:: _static/chimere_admin_import_CSV.png - -- **Web address/source file (mandatory)**: your CSV file could be distant or a - local file. You'll have to fill one of the two fields. - -.. _osm-import: - -OpenStreetMap import -******************** - -.. image:: _static/chimere_admin_import_OSM.png - -To import from OSM Chimère use the XAPI API of OSM. - -- **Web address (mandatory)**: XAPI url used to import data. This field should - be filled with a default address. By default the MapQuest server is used as it - seems to be the more robust. If you experience problems with OSM import, check - the availability of the XAPI server used and eventually change it. -- **Filter area (mandatory)**: draw the bounding box you want to use for your - OSM import. -- **Filter type (mandatory)**: choose if you want to import way or nodes. -- **Filter tag (mandatory)**: choose the OSM key/value couple used to filter OSM - data. A link to the `OSM Map features page - `_ is provided to help you - find appropriate values. -- **Refresh button**: this button convert your choices to appropriate XAPI args. - You have to hit this button before validating the form. - -Importing -********* - -Once your new import item created, select it in the import object list, choose -the **Import** action and validate. - -The import should be processing normally. If not, an explicit error message -should be printed in the state column of your import. - -You can also launch imports with the CLI (ideal for crontab jobs). In the -project directory you only need to launch the command:: - - ./manage.py chimere_import - -- *import_id* is the import ID - -If you launch the command without *import_id* the list of imports available is -presented and you can choose one. - -Managing imported data -********************** - -All new imported items have the state **Imported**. To make them available on -the map you'll have to validate them. If you don't want some items to be visible -on the map, instead of deleting them it is recommended to set them to the state -**Disabled**. So on the next update from the source, rather than appear as new -items they remain disabled. - -.. Warning:: - Be careful with duplicates between your existing data and imported data. This - is particularly important if you want to export your data to OSM. - -Exporting ---------- - -Export to CSV/KML/Shapefile -*************************** - -Directly from the :ref:`geographic items list ` you -can export to the chosen format. All you have to do is to select the desired -items, choose the appropriate action in the action list and validate. - -You can also launch exports with the CLI (ideal for crontab jobs). In the -project directory you only need to launch the command:: - - ./manage.py chimere_export \ - - -- *subcategory_id* is the ID of the chosen subcategory -- *CSV|KML|SHP* is the chosen format -- *marker|route* is to get marker or route -- *filename* is the output filename - -If you launch the command without arguments you will be prompted for the choice -to make for your export. - - -Export to OSM -************* - -.. Warning:: - If you are not sure of what you are doing with OSM export: don't do it! It is - really important to not mess with others' data. - -.. Note:: - Only export of OSM nodes are managed. - -OSM export is not that easily managed. First (if not yet done) you'll have to -define an import (:ref:`see above ` for details). This will enable -to determine: - -- the area concerned by your export. -- the key/value tag to append to your new/updated items. -- the subcategories concerned by your export. If you think that some items in - these subcategories should not be in OSM database (because there are not - relevant or because of license issues) beforehand mark them as **Not for OSM** - in the *import fields* of the :ref:`geographic items forms - `. - - -The OSM export in Chimère is designed to be the more preservative possible in -regards to OSM database. That's why before any export an import is done. If -the new import has updated data, these new data will overload data in your -Chimère (if you don't want that: don't do re-imports so dont do exports). All -pending imported items should have been treated before doing an export. - -To launch an export select the appropriate *Import* object in the imports list. -Then select the **Export to OSM** action and validate. -Then you'll be asked for your OSM username and password and the API you want to -use. If you regularly use Chimère to do export, it is recommended to create an -OSM specific account for that. -The test API is available to make export test. If you want to use the test -API you'll have to create a specific account on the test platform. - -.. Warning:: - The data on the test platform are not synced with the main platform. You won't - have the same data than the ones you got with XAPI. - -Once all this field filled, you can (finally!) launch the export. - -When exporting tags are automatically added/updated: - -- *name*: get from the item name in Chimère. -- *source*: to identify Chimère as a source. diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index ee1dd6f..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. Chimère documentation master file, created by - sphinx-quickstart on Wed Feb 15 00:42:28 2012. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to Chimère's documentation! -=================================== - -.. toctree:: - :maxdepth: 2 - - install - upgrade - configuration - administration - import_export - customisation diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index ea27efc..0000000 --- a/docs/install.rst +++ /dev/null @@ -1,290 +0,0 @@ -.. -*- coding: utf-8 -*- - -============ -Installation -============ - -:Author: Étienne Loks -:date: 2012-11-28 -:Copyright: CC-BY 3.0 - -This document presents the installation of Chimère. -It has been updated for version 2.0.0. - -Prerequisites -************* - - - `Apache `_ version 2.x - - `Python `_ versions 2.6 or 2.7 - - `Django `_ >= version 1.4 - - `South `_ - - `Postgres `_ >= version 8.x - - `Gettext `_ - - `Psycopg2 `_ - - `Python Imaging Library `_ - - `Pyexiv2 `_ - - `Beautiful Soup `_ - - python-simplejson - - python-gdal - - `Lxml `_ - - `Jquery `_ version 1.7.1 or better - - `Jquery-ui `_ - - `Universal Feed Parser `_ - -geodjango is a part of django since version 1.0 but it has some specific -(geographically related) additional dependencies: - - - `geos `_ 3.0.x - - `proj.4 `_ 4.4 to 4.6 - - `postgis `_ versions 1.2.1 or 1.3.x - - `gdal `_ - - -Optionaly (but recommanded): - - - `tinymce `_ - - `gpsbabel `_ - - django-celery if you want to manage large imports - - -The simpliest way to obtain these packages is to get them from your favorite -Linux distribution repositories. For instance on Debian Wheezy:: - - apt-get install apache2 python python-django python-django-south \ - postgresql-9.1 gettext python-psycopg2 python-imaging \ - python-pyexiv2 python-beautifulsoup python-simplejson python-gdal \ - python-lxml libjs-jquery libjs-jquery-ui python-feedparser \ - libgeos-3.3.3 proj-bin postgresql-9.1-postgis gdal-bin \ - tinymce gpsbabel python-django-celery javascript-common - - -On Debian Squeeze (you need to activate backports):: - - apt-get install -t squeeze-backports python-django libjs-jquery - - apt-get install apache2 python python-django python-django-south \ - postgresql-8.4 gettext python-psycopg2 python-imaging \ - python-pyexiv2 python-beautifulsoup python-simplejson python-gdal \ - python-lxml libjs-jquery libjs-jquery-ui python-feedparser \ - libgeos-3.2.0 proj-bin postgresql-8.4-postgis gdal-bin \ - tinymce gpsbabel javascript-common - -The package *python-django-celery* doesn't exist for Debian Squeeze. - -If these packages do not exist in your distribution's repository, please refer -to the applications' websites. - -Database configuration -********************** - -Now that postgres and postgis are installed, you need to create a new user for -Chimère:: - - su postgres - createuser --echo --adduser --createdb --encrypted --pwprompt chimere-user - -Then, you have to create the database and initialize the geographic types (adapt -the paths accordingly to your needs):: - - PG_VERSION=9.1 # 8.4 for debian Squeeze - createdb --echo --owner chimere-user --encoding UNICODE chimere "My Chimère database" - createlang plpgsql chimere # only necessary on Debian Squeeze - psql -d chimere -f /usr/share/postgresql/$PG_VERSION/contrib/postgis-1.5/postgis.sql - psql -d chimere -f /usr/share/postgresql/$PG_VERSION/contrib/postgis-1.5/spatial_ref_sys.sql - -Installing the sources -********************** - -.. Note:: - If you are considering to contribute on Chimère get the Git master. - -Choose a path to install your Chimère:: - - INSTALL_PATH=/var/local/django - mkdir $INSTALL_PATH - -From an archive -+++++++++++++++ - -The last "stable" version is available in this `directory `_. -Take care of getting the last version in the desired X.Y branch (for instance -the last version for the 1.0 branch is version 1.0.2).:: - - wget http://www.peacefrogs.net/download/chimere -q -O -| html2text - (...) - [[ ]] chimere-1.0.0.tar.bz2 17-Nov-2010 16:51 53K - [[ ]] chimere-1.0.1.tar.bz2 17-Nov-2010 16:51 53K - [[ ]] chimere-1.0.2.tar.bz2 17-Nov-2010 16:51 53K - (...) - - wget http://www.peacefrogs.net/download/chimere/chimere-1.0.2.tar.bz2 - -Download, unpack and move the files in an apache user (www-data for Debian) -readable directory:: - - cd $INSTALL_PATH - tar xvjf chimere-last.tar.bz2 - chown -R myusername:www-data chimere - -From the Git repository -+++++++++++++++++++++++ - -Another solution is to get it from the Git repository:: - - cd $INSTALL_PATH - git clone git://www.peacefrogs.net/git/chimere - cd chimere - git tag -l # list tagged versions - git checkout v2.0 # checkout the desired version - - -Creating a custom project template -********************************** - -There, a default project is provided (*example_project*). Copy and modify -it (or get another project based on Chimère):: - - cd $INSTALL_PATH/chimere - cp -ra example_project mychimere_project - -Your project name is used for the name of the Python package of your template. -As a Python package it should follow the rule of Python variable name: -it must contain at least one letter and can have a string of numbers, letters and -underscores ("_") to any length. Don't use accentuated letters. Don't begin the -name by "_" because it has special significance in Python. - -In your Chimère application directory create *local_settings.py* to fit to your -configuration. -A base template is provided (*local_settings.py.example*) and short descriptions -of the more relevant fields are given below (at least check them). Most of -these settings are initialized in *settings.py*. :: - - cd $INSTALL_PATH/chimere/mychimere_project - cp local_settings.py.sample local_settings.py - vim local_settings.py - -:Fields: - - * DATABASES: parameters for the database - * PROJECT_NAME: name of the project - * SECRET_KEY: a secret key for a particular Django installation. This is - used to provide cryptographic signing, and should be set to a unique, - unpredictable value. **Change it!** - * ROOT_URLCONF: url configuration for your project something like: - 'mychimere_project.urls' - * EMAIL_HOST: smtp of an email server to send emails - * TINYMCE_URL: url to tinymce path (default is appropriate for a Debian - installation with tinymce package installed) - * JQUERY_JS_URLS: list of jquery and jquery-ui javascript urls (default is - appropriate for a Debian installation with libjs-jquery libjs-jquery-ui - packages installed) - * JQUERY_CSS_URLS: list of jquery and jquery-ui CSS urls (default is - appropriate for a Debian installation with libjs-jquery libjs-jquery-ui - packages installed) - * GPSBABEL: path to gpsbabel (default is appropriate for a Debian - installation with gpsbabel package installed) - * TIME_ZONE: local time zone for this installation - * LANGUAGE_CODE: language code for this installation - -Manage media path permission:: - - cd $INSTALL_PATH/chimere/mychimere_project - chown -R user:www-data media - chmod -R g+w media - -Create log file:: - - mkdir /var/log/django - touch /var/log/django/chimere.log - chown -R root:www-data /var/log/django/ - chmod -R g+w /var/log/django/ - -Regroup static files in one path:: - - cd $INSTALL_PATH/chimere/mychimere_project - ./manage.py collectstatic - -Compiling languages -******************* - -If your language is available in the directory *chimere/locale/*, you will just -need to get it compiled. This can be done with the following command (here, -**fr** stands for French, replace it with the appropriate language code):: - - cd $INSTALL_PATH/chimere/chimere/ - django-admin compilemessages -l fr - -If your language is not available, feel free to create the default po file and -to submit it, contributions are well appreciated. Procedure is as follows: - -You first need to create the default po file (of course, replace **fr** -according to the language you choose to create):: - - django-admin makemessages -l fr - -There should now be a *django.po* file in *locale/fr/LC_MESSAGES*. Complete it -with your translation. - -Now that the translation file is completed, just compile it the same way you -would have if the language file was already available. - -Database initialisation -*********************** - -Create the appropriate tables (still being in your Chimère project directory):: - - cd $INSTALL_PATH/chimere/mychimere_project - ./manage.py syncdb - -You will be prompted for the creation of an administrator account -(administration can be found at: http://where_is_chimere/admin/). Then you have -to create tables managed with Django-South:: - - ./manage.py migrate - -The database is set, congratulations! - -If you want to populate your installation with default data (don't do this on -an already populated instance!):: - - ./manage.py loaddata ../chimere/fixtures/default_data.json - -Webserver configuration -*********************** - -Apache configuration with mod_wsgi -++++++++++++++++++++++++++++++++++ - -Install *mod_wsgi* for Apache:: - - apt-get install libapache2-mod-wsgi - - -Create and edit a configuration for Chimère:: - - cp $INSTALL_PATH/chimere/apache/django.wsgi \ - $INSTALL_PATH/chimere/apache/mydjango.wsgi - vim $INSTALL_PATH/chimere/apache/mydjango.wsgi - cp $INSTALL_PATH/chimere/apache/apache-wsgi.conf \ - /etc/apache2/sites-available/chimere - vim /etc/apache2/sites-available/chimere - # create log dir - mkdir /var/log/apache2/chimere/ - chown www-data /var/log/apache2/chimere/ - -Adapt the files *mydjango.wsgi* (with the correct sys path and the correct -module) and Apache *chimere* (with the correct servername and correct paths). - -To activate the website, reload apache:: - - a2ensite chimere - /etc/init.d/apache2 reload - -If you encounter problem with the upload of files with Unicode chars in their -names, activate the appropriate locale in Apache. On a Debian server with UTF-8 -as default encoding, in the file */etc/apache2/envvars* uncomment the following -line:: - - . /etc/default/locale - - diff --git a/docs/upgrade.rst b/docs/upgrade.rst deleted file mode 100644 index d44ae02..0000000 --- a/docs/upgrade.rst +++ /dev/null @@ -1,311 +0,0 @@ -.. -*- coding: utf-8 -*- - -======= -Upgrade -======= - -:Author: Étienne Loks -:date: 2012-10-08 -:Copyright: CC-BY 3.0 - -This document presents the upgrade of Chimère. -It has been updated for version 2.0.0. - -.. Warning:: - Before any upgrade backup the database and all your installation files - (specially if you have made changes to them). - -The process for migration requires a basic knowledge of Git and Linux CLI. It is -*not* an easy process. A work is currently done to easy the upgrade in later -versions (>2.0) of Chimère. - -If several versions have been published, you should repeat all upgrading steps. -For instance to upgrade from v1.1 to v2.0 you should first upgrade to v1.2 then -to v2.0. The only optional step is the integration of your customisations. - -The current stable version is 2.0. - -.. Note:: - If you are considering to contribute on Chimère get the Git master. - -The instructions are given for Debian Squeeze and Debian Wheezy. - - -Getting new versions of dependencies ------------------------------------- - -Version 1.1 -> 1.2 -****************** - -.. code-block:: bash - - apt-get install python-lxml libjs-jquery gpsbabel python-gdal - -Version 1.2 -> 2.0 -****************** - -Debian Squeeze -++++++++++++++ -Activate the backports: http://backports-master.debian.org/Instructions/ -Then install the new dependencies:: - - apt-get install -t squeeze-backports python-django python-django-south \ - python-simplejson libjs-jquery-ui python-pyexiv2 \ - python-feedparser javascript-common libjs-jquery - -Debian Wheezy -+++++++++++++ - -.. code-block:: bash - - apt-get install python-django-south python-simplejson libjs-jquery-ui \ - python-pyexiv2 python-feedparser javascript-common - -If you are planning to do major import consider the install of `Celery -`_. - -.. code-block:: bash - - apt-get install python-django-celery python-kombu - -Getting the new sources ------------------------ - -First of all you have to get the new version of the source code. -For the upgrade process, the source code has to be from the Git -repository. - -To simplify further instructions, some environment variables are -initialized. - -.. code-block:: bash - - CHIMERE_PATH=/srv/chimere - CHIMERE_TAG=v1.2.0 # version 1.1 -> 1.2 - CHIMERE_TAG=v2.0-RC3 # version 1.2 -> 2.0 - CHIMERE_TAG=master # version 2.0 -> master - CHIMERE_LOCALNAME=mychimere - -Your local name is used for the name of your local Git branch and the Python -package. As a Python package it should follow the rule of Python variable name: -it must be at least one letter and can have a string of numbers, letters and -underscores ("_") to any length. Don't begin the name by "_" because it has special -significance in Python. - -From a previous Git installation -******************************** - -.. code-block:: bash - - cd $CHIMERE_PATH - git checkout -b $CHIMERE_LOCALNAME # only if you haven't created yet a local branch - git stash # if you have uncommited changes - git checkout master - git pull - git checkout $CHIMERE_LOCALNAME - git rebase $CHIMERE_TAG - -From a previous tarball installation -************************************ - -First remove your old installation and get the Git version: - -.. code-block:: bash - - cd $CHIMERE_PATH - cd .. - rm -rf $CHIMERE_PATH - git clone git://www.peacefrogs.net/git/chimere - cd chimere - git checkout $CHIMERE_TAG - git checkout -b $CHIMERE_LOCALNAME - - -Update basic settings -********************* - -Version 1.1 -> 1.2 -++++++++++++++++++ - -.. code-block:: bash - - CHIMERE_APP_PATH=$CHIMERE_PATH/chimere - vim $CHIMERE_APP_PATH/settings.py - -Add the following lines (adapted for your jquery and gpsbabel installation): - -.. code-block:: python - - JQUERY_URL = SERVER_URL + 'jquery/jquery-1.4.4.min.js' - GPSBABEL = '/usr/bin/gpsbabel' - # simplify with an error of 5 meters - GPSBABEL_OPTIONS = 'simplify,crosstrack,error=0.005k' - -Version 1.2 -> 2.0 -++++++++++++++++++ - -Project template -................ -Create a new project template: - -.. code-block:: bash - - cd $CHIMERE_PATH - cp -ra $CHIMERE_PATH/example_project $CHIMERE_LOCALNAME - CHIMERE_APP_PATH=$CHIMERE_PATH/$CHIMERE_LOCALNAME - -local_settings -.............. -A *local_settings* file is now used. - -.. code-block:: bash - - cd $CHIMERE_APP_PATH - cp local_settings.py.sample local_settings.py - vim local_settings.py - -Report your old settings from *settings.py* to *local_settings.py* (at least the -database configuration). -The setting *ROOT_URLCONF* must be set to **value_of_your_localname.urls**. - -logs -.... -Logging is now enabled by default in the file */var/log/django/chimere.log*. - -.. code-block:: bash - - mkdir /var/log/django - touch /var/log/django/chimere.log - chown www-data -R /var/log/django - -Static files -............ - -Now static files are managed with *django.contrib.staticfiles*. - -.. code-block:: bash - - cd $CHIMERE_APP_PATH - ./manage.py collectstatic - -Move old static files to the new static directory: - -.. code-block:: bash - - cp -ra $CHIMERE_PATH/chimere/static/* $CHIMERE_APP_PATH/static/ - cp -ra $CHIMERE_PATH/chimere/static/icons/* $CHIMERE_APP_PATH/media/icons/ - cp -ra $CHIMERE_PATH/chimere/static/upload $CHIMERE_APP_PATH/media/ - -Webserver configuration -....................... -If you are using Apache and WSGI to serve your Chimère, change your WSGI -configuration file to point to the correct settings: -**value_of_your_localname.settings**. - -Change your webserver directive to point to the correct static directory from -**your_chimere_path/chimere/static** to -**your_chimere_path/your_local_name/static**. - -Version 2.0 -> master -+++++++++++++++++++++ - -Update settings and static files. - -.. code-block:: bash - - cp $CHIMERE_PATH/example_project/settings.py $CHIMERE_LOCALNAME - ./manage.py collectstatic - -Migrate database ----------------- - -Version 1.1 -> 1.2 -****************** - -Migration scripts test your installation before making changes so you probably -won't have any lost but by precaution before running these scripts don't forget -to backup your database. -You can also make a copy of your current database into a new database and make -the new installation to this new database. - -The gdal binding for Python is necessary to run the upgrade scripts (available -in the python-gdal package in Debian). - -If you run the migration scripts in a production environnement stop the old -instance of Chimère before executing the migration script. - -In *settings.py* verify that **chimere.scripts** is in the *INSTALLED_APPS*. - -After that in the Chimère directory just execute the script. - -.. code-block:: bash - - cd $CHIMERE_APP_PATH - python ./scripts/upgrade.py - -Version 1.2 -> 2.0 -****************** - -Django South is now used to manage database migrations. - -.. code-block:: bash - - cd $CHIMERE_APP_PATH - ./manage.py syncdb - ./manage.py migrate chimere 0001 --fake # fake the database initialisation - ./manage.py migrate chimere - -A description field is now available for markers. If you would like to move -values of an old *Property model* to this new field, a script is available. - -.. code-block:: bash - - cd $CHIMERE_APP_PATH - ../chimere/scripts/migrate_properties.py - # follow the instructions - -Version 2.0 -> master -********************* - -.. code-block:: bash - - cd $CHIMERE_APP_PATH - ./manage.py syncdb - ./manage.py migrate chimere - -Update translations -------------------- - -Version 1.1 -> 1.2 -****************** - -.. code-block:: bash - - cd $CHIMERE_APP_PATH - ./manage.py compilemessages - -Version 1.2 -> 2.0 -> master -**************************** - -.. code-block:: bash - - cd $CHIMERE_PATH/chimere - django-admin compilemessages - -Forcing the refresh of visitor's web browser cache --------------------------------------------------- - -Major changes in the javascript has been done between versions, many of your -users could experience problems. There are many tricks to force the refresh -of their cache. One of them is to change the location of statics files. To do -that edit your local_settings.py and change:: - - STATIC_URL = '/static/' - -to:: - - STATIC_URL = '/static/v2.0.0/' - -Then change the webserver directive to point to your new path. -Restart the web server to apply this changes. - -- cgit v1.2.3