[doc] Restructure the documentation
* Create a new index file
* Move the sphinx configuration files do the documentation root
* Move book/README to dev/documenting.rst
* Move book/mode_plan.py to tools/
* Move book/en/images to images
* Move book/en/* to book/
* Move changelogs to changes/*
* Adapt the Makefile
* Add a title to the javascript api index
Related to #4832808
.. -*- coding: utf-8 -*-.._templates:Templates=========Templates are the entry point for the |cubicweb| view system. As seenin :ref:`views_base_class`, there are two kinds of views: thetemplatable and non-templatable.Non-templatable views---------------------Non-templatable views are standalone. They are responsible for all the detailssuch as setting a proper content type (or mime type), the proper documentheaders, namespaces, etc. Examples are pure xml views such as RSS or Semantic Webviews (`SIOC`_, `DOAP`_, `FOAF`_, `Linked Data`_, etc.), and views which generatebinary files (pdf, excel files, etc.).._`SIOC`: http://sioc-project.org/.._`DOAP`: http://trac.usefulinc.com/doap.._`FOAF`: http://www.foaf-project.org/.._`Linked Data`: http://linkeddata.org/To notice that a view is not templatable, you just have to set theview's class attribute `templatable` to `False`. In this case, itshould set the `content_type` class attribute to the correct MIMEtype. By default, it is text/xhtml. Additionally, if your viewgenerate a binary file, you have to set the view's class attribute`binary` to `True` too.Templatable views-----------------Templatable views are not concerned with such pesky details. Theyleave it to the template. Conversely, the template's main job is to:* set up the proper document header and content type* define the general layout of a document* invoke adequate views in the various sections of the documentLook at :mod:`cubicweb.web.views.basetemplates` and you will find the basetemplates used to generate (X)HTML for your application. The most importanttemplate there is :class:`~cubicweb.web.views.basetemplates.TheMainTemplate`..._the_main_template_layout:TheMainTemplate~~~~~~~~~~~~~~~.._the_main_template_sections:Layout and sections```````````````````A page is composed as indicated on the schema below :..image:: ../../images/main_template.pngThe sections dispatches specific views:*`header`: the rendering of the header is delegated to the`htmlheader` view, whose default implementation can be found in``basetemplates.py`` and which does the following things:* inject the favicon if there is one* inject the global style sheets and javascript resources* call and display a link to an rss component if there is one available it also sets up the page title, and fills the actual`header` section with top-level components, using the `header` view, which:* tries to display a logo, the name of the application and the `breadcrumbs`* provides a login status area* provides a login box (hiden by default)*`left column`: this is filled with all selectable boxes matching the`left` context (there is also a right column but nowadays it is seldom used due to bad usability)*`contentcol`: this is the central column; it is filled with:* the `rqlinput` view (hidden by default)* the `applmessages` component* the `contentheader` view which in turns dispatches all available content navigation components having the `navtop` context (this is used to navigate through entities implementing the IPrevNext interface)* the view that was given as input to the template's `call` method, also dealing with pagination concerns* the `contentfooter`*`footer`: adds all footer actions..note:: How and why a view object is given to the main template is explained in the :ref:`publisher` chapter.Configure the main template```````````````````````````You can overload some methods of the:class:`~cubicweb.web.views.basetemplates.TheMainTemplate`, in order to fulfilyour needs. There are also some attributes and methods which can be defined on aview to modify the base template behaviour:*`paginable`: if the result set is bigger than a configurable size, your result page will be paginated by default. You can set this attribute to `False` to avoid this.*`binary`: boolean flag telling if the view generates some text or a binary stream. Default to False. When view generates text argument given to `self.w`**must be a unicode string**, encoded string otherwise.*`content_type`, view's content type, default to 'text/xhtml'*`templatable`, boolean flag telling if the view's content should be returned directly (when `False`) or included in the main template layout (including header, boxes and so on).*`page_title()`, method that should return a title that will be set as page title in the html headers.*`html_headers()`, method that should return a list of HTML headers to be included the html headers.You can also modify certain aspects of the main template of a pagewhen building a url or setting these parameters in the req.form:*`__notemplate`, if present (whatever the value assigned), only the content view is returned*`__force_display`, if present and its value is not null, no pagination whatever the number of entities to display (e.g. similar effect as view's `paginable` attribute described above.*`__method`, if the result set to render contains only one entity and this parameter is set, it refers to a method to call on the entity by passing it the dictionary of the forms parameters, before going the classic way (through step 1 and 2 described juste above)*`vtitle`, a title to be set as <h1> of the contentOther templates~~~~~~~~~~~~~~~There are also the following other standard templates:*:class:`cubicweb.web.views.basetemplates.LogInTemplate`*:class:`cubicweb.web.views.basetemplates.LogOutTemplate`*:class:`cubicweb.web.views.basetemplates.ErrorTemplate` specializes:class:`~cubicweb.web.views.basetemplates.TheMainTemplate` to do proper end-user output if an error occurs during the computation of TheMainTemplate (it is a fallback view).