From 14fa30efc6e6f3523e93facf38402d8a94db4803 Mon Sep 17 00:00:00 2001 From: Kostas Papadimitriou Date: Tue, 31 Jul 2012 21:50:12 +0300 Subject: [PATCH] Update documentation and Changelog --- Changelog | 28 +++++++-- docs/source/index.rst | 152 ++++++++++++++++++++++++++++++++++++------------- 2 files changed, 136 insertions(+), 44 deletions(-) diff --git a/Changelog b/Changelog index cefad88..4d2a680 100644 --- a/Changelog +++ b/Changelog @@ -1,11 +1,29 @@ Changelog ========= -v0.7.0 ------- -* Integrated FAQ's application -* Integrated client downloads application -* +v0.11.0 +------- + +* Userguide application +* FAQ's application +* Client downloads application +* New service models +* New html/css theme +* Responsive html content +* Userguide/FAQ's import from rst tool +* Django auth context processor as snf-webproject hook +* Major database updates. Use:: + + $ snf-manage syncdb + $ snf-image migrate + + to update existing databases. Additionally you can initiate service models and + media categories for FAQ/Userguide applications by loading the provided + fixtures:: + + $ snf-manage loaddata cloudcms_media_categories + $ snf-manage loaddata cloudcms_default_services + v0.6.1 ------ diff --git a/docs/source/index.rst b/docs/source/index.rst index 27f78a3..2135ebe 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,10 +16,11 @@ The project created to power websites that provide information about the At the current state the application provides the following features: -* basic cms funcionality (adding/removing/editing hierarchical pages) -* blog application +* Basic cms funcionality (adding/removing/editing hierarchical pages) +* Blog application * FAQ application * Resources application (for presentations, technical papers etc.) +* User guide application .. _django: http://www.djangoproject.com .. _feincms: http://feinheit.ch/media/labs/feincms/ @@ -40,16 +41,21 @@ defined to find which django settings are required for cms to work. .. _snf-webproject: http://docs.dev.grnet.gr/snf-webproject +.. note:: + + Synnefo components and additional required packages can be obtained from + ``apt.dev.grnet.gr`` debian repository. To enable the repository add the + following lines in ``/etc/apt/sources.list.d/apt.dev.grnet.list``:: + + deb http://apt.dev.grnet.gr squeeze main + deb-src http://apt.dev.grnet.gr squeeze main + Install required packages:: apt-get install snf-common snf-webproject apt-get install python-django-feincms python-django-pagination python-django -.. note:: - ``python-django-feincms`` and ``python-django-pagination`` are not provided - currently on debian stable but can be backported from sid. - then, install ``snf-cloudcms`` package:: apt-get install snf-cloudcms @@ -159,55 +165,123 @@ permissions:: Admin guide =========== -Bind blog to a cms page ------------------------ +Bind blog application to a cms page +----------------------------------- -1. Create a page on the cms tree. +1. Create a page on the cms tree using the ``Blog template`` template. 2. On the region you want the blog content to appear (list of posts, and post details), add an ``Application content`` content type and choose ``Cloud blog`` from the drop down list. 3. On navigation extension settings of the page, choose ``blog categories``. -Bind FAQs to a cms page ------------------------- -1. Create a page on the cms tree. -2. On the region you want the blog content to appear (list of posts, and post - details), add an ``Application content`` content type and choose ``Cloud - FAQ`` from the drop down list. +Bind FAQs application to a cms page +----------------------------------- + +1. Create a page on the cms tree using the ``FAQ's template`` template. +2. On the top region add an ``Application content`` content type and choose + ``Cloud FAQ`` from the drop down list. 3. *Optional:* On navigation extension settings of the page, choose ``faq categories``. -Bind resources to a cms page ----------------------------- + +Bind resources application to a cms page +---------------------------------------- 1. Create a page on the cms tree. 2. On the region you want the resources to appear append a ``Resources list`` content type. -FAQ's guide ------------ - -Adding a question -^^^^^^^^^^^^^^^^^ - -1. Open the faq's list in admin panel (``/cmsmanage/cloudcmsfaq/question/``) - and press the ``Add faq`` button. -2. Fill in the required fields: - * Title, the question. - * Author, the question author. - * Slug, the url to be used for the current question - (should get autocompleted after filling the title field) - * Category, the category of the question. - -3. On the main content area tab add the content you want to be displayed as the - answer of the question. - * ``Rich text`` (can be added by pressing the icon with the pencil) and - ``Raw content`` may contain html text. - -4. Click save. - +Bind Userguide application to a cms page +----------------------------------------- + +1. Create a page on the cms tree using the ``Userguide template`` template. +2. On the top region add an ``Application content`` content type and choose + ``Cloud user guide`` from the drop down list. + + +Importing FAQ's and Userguide entries from rst files +---------------------------------------------------- + +Cloudcms provides a way to import content for faq and userguide applications +from rst files. This allows you to keep the guide and faq content tracked in +rst markup format seperately from the cms database (e.g. in a git repository +maintained by your documentation team), and update the cms content on demand. + +.. warning:: + Notice that you can still edit the FAQ's and Userguide entries using the + corresponding section in the cms admin interface, but beware that mixing both + methods is not recommended since it's ineffective and prone to data loss. + +To access the import form, login to the admin site and open the following url:: + + https://cms.com/cmsmange/rstimport/ + +The required file should be a zip archive containing files of the following +structure (similar to common sphinx project structure):: + + + + ├── README.rst + └── source + ├── conf.py + ├── faq + │   ├── cyclades.rst + │   ├── index.rst + │   ├── okeanos.rst + │   └── pithos.rst + ├── images + │   ├── cyclades + │   │   ├── image10.png + │   │   └── image9.png + │   ├── faq + │   │   └── faq_image1.png + │   ├── intro_img_cyclades.png + │   └── pithos_guide + │   └── image2.png + ├── index.rst + └── userguide + ├── cyclades.rst + ├── index.rst + ├── pithos.rst + └── quick-intro.rst + +.. warning:: + Notice that directory names ``faq``, ``userguide`` are mandatory. + + +By submiting the form the application will act as follows + +- Clean existing data if ``clean data`` was checked. This includes **all** + FAQ/Userguide entries, FAQ categories and media files linked to them. +- Will search for files named after the ``CMS_RST_IMPORT_SERVICE_FILE_MAP`` + setting both in ``faq`` and ``userguide`` directories, to identify which + service the contents of the file are referred to. The default setting value + is (maps files to service slugs):: + + DEFAULT_SERVICE_MAP = { + 'cyclades': 'cyclades', + 'okeanos': 'okeanos', + 'pithos': 'pithos' + } + +- For the FAQ entries which are structured by service/category, the importer will + parse secondary headings as FAQ categories and tertiary headings as FAQ + entries. +- For the Userguide entries which only require the service to be linked to, the + secondary headings and their content are parsed as Userguide entries +- For both FAQ and Userguide entries the linked images will be uploaded + in the media files application and the html anchors will get updated + containing a valid cms link. + +.. warning:: + Import helper uses python ``docutils`` to parse .rst files contents. This + means that additional sphinx directives like ``:ref:`` or ``.. code-block`` + won't be parsed as excpected. This behaviour might get improved in future + versions. Until then try to compromise your content to `basic rst format`_. + +.. _basic rst format: http://docutils.sourceforge.net/docs/user/rst/quickstart.html .. include:: ../../Changelog -- 1.7.10.4