Merge branch 'release/0.22.0'

.readthedocs.yml

@@ -0,0 +1,8 @@
+# Build PDF & ePub
+formats:
+    - htmlzip
+    - epub
+    - pdf
+python:
+    version: 3.5
+requirements_file: ./stable-req.txt

README.md

@@ -11,8 +11,10 @@
 # On MacOS, use brew
 # brew install python3
 
-pip3 install sphinx
-pip3 install sphinx-intl
+pip3 install sphinx  --user
+pip3 install sphinx-intl --user
+pip3 install recommonmark --user
+pip3 install pygments-markdown-lexer --user
 ```
 
 ## Prepare translations

conf.py

@@ -15,6 +15,9 @@
 import sys
 import os
 import shutil
+import recommonmark
+from recommonmark.parser import CommonMarkParser
+from recommonmark.transform import AutoStructify
 
 # import sphinx_rtd_theme
 #
@@ -56,7 +59,7 @@
 # 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.
@@ -69,14 +72,22 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.viewcode'
+    'sphinx.ext.viewcode',
+    'sphinx.ext.ifconfig',
+    'pygments_markdown_lexer'
+
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+source_parsers = {
+    '.md': CommonMarkParser,
+}
 # The suffix of source filenames.
-source_suffix = '.rst'
+#source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+enable_eval_rst = True
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -93,9 +104,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.21.0'
+version = '0.22.0'
 # The full version, including alpha/beta/rc tags.
-release = 'beta 0.21.0'
+release = 'beta 0.22.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -236,26 +247,26 @@
 
 # -- Options for LaTeX output ---------------------------------------------
 
-latex_engine = 'xelatex'
+#latex_engine = 'xelatex'
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     'papersize': 'a4paper',
-    'pxunit': '0.48bp', # 150dpi
+    'pxunit': '0.50bp', # 150dpi
     # The font size ('10pt', '11pt' or '12pt').
     #
     'pointsize': '9pt',
     # Remove blank pages
     # http://stackoverflow.com/questions/5422997/sphinx-docs-remove-blank-pages-from-generated-pdfs
-    'classoptions': ',oneside',
+    #'classoptions': ',oneside',
     # Latex figure (float) alignment
     #
-    'figure_align': 'H',
-    'geometry': '\\usepackage[vmargin=2.5cm, hmargin=3cm]{geometry}',
+    #'figure_align': 'H',
+    #'geometry': '\\usepackage[vmargin=2.5cm, hmargin=3cm]{geometry}',
     # Additional stuff for the LaTeX preamble.
     #
-    'preamble': '\\setcounter{tocdepth}{3}',
-    'fncychap': '\\usepackage[Bjornstrup]{fncychap}',
+    'preamble': '\\setcounter{tocdepth}{2}',
+    #'fncychap': '\\usepackage[Bjornstrup]{fncychap}',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
@@ -392,3 +403,12 @@
 
 # If false, no index is generated.
 #epub_use_index = True
+
+# app setup hook
+def setup(app):
+    app.add_config_value('recommonmark_config', {
+        'auto_toc_tree_section': 'Contents',
+        'enable_eval_rst': True,
+        'enable_auto_doc_ref': True,
+    }, True)
+    app.add_transform(AutoStructify)

developer/first-steps/index.rst

@@ -8,6 +8,7 @@ First steps
    requirements
    installation
    vagrant
+   php_server
    manual_config
    upgrading
    moving

developer/first-steps/installation.rst

@@ -20,7 +20,7 @@ in your projects and save them using Git, not only your theme. Of course we adde
 prevent your configuration setting and entry points to be commited in your *Git* history. That way you can have
 different configuration on development and on your production server without bothering about merge conflicts.
 
-.. note:: 
+.. note::
 
     For *Windows* users, ``bin/roadiz themes:generate --symlink --relative FooBar`` command can be used
     without ``--relative`` option to create **absolute symlinks**. You can even install your theme assets as
@@ -29,14 +29,13 @@ different configuration on development and on your production server without bot
     your assets. You should use *symlinks* if possible to prevent update issues.
 
 
-================================
 Dealing with Roadiz environments
-================================
+--------------------------------
 
 .. _install environment:
 
 Installation environment
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Once you’ve succedded to download Roadiz and its dependencies. You’ll have to setup its database
 and every informations needed to begin your website.
@@ -54,27 +53,27 @@ At the end of the install process, you will be invited to remove the ``install.p
 website final URL.
 
 Development environment
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
 Roadiz *production* environment is not made for developing your own themes and extending back-office features.
 As the same way as *install* environment, we prepared a *dev* environment to disable resources caching and enable
 debug features. You’ll find a ``dev.php`` file at your website root which was generated at ``composer install`` command.
 As well as *install.php* entry point, you’ll need to add your own IP address to filter who can access to your *dev* environment.
 
 Preview environment
--------------------
+^^^^^^^^^^^^^^^^^^^
 The *preview* environment is not a real one as it only adds a flag to Roadiz’ Kernel to enable
 back-office users to see unpublished nodes. By default, it is available using ``preview.php``
 entry point, unless you decide to remove it.
 
 Production environment
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^
 This is the default ``index.php`` entry point which will be called by all your visitors.
 There is no restriction on it and it will wake up Roadiz application using the strongest
 caching policies. So it’s not recommended for development usage (you would have to flush caches
 each time your change something in the code).
 
 Clear cache environment
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
 The *clear_cache* environment is only meant to empty Roadiz cache without waking up
 the whole application. It can be useful if you are using a op-code cache like *APC* or
 native PHP *OPcache*. These special caches can’t be purged from command line utilities,

developer/first-steps/php_server.md

@@ -0,0 +1,33 @@
+# Using PHP server for development
+
+If *Vagrant* is too heavy for your purpose, you can simply use *PHP built-in server*.
+
+Following command will launch a web-server listening on all IP addresses on port
+8080. We also use a dedicated *router* file to serve static and generated resources:
+
+```bash
+# Create a new Roadiz project
+composer create-project roadiz/standard-edition
+# Create a new theme for your project
+cd standard-edition
+bin/roadiz themes:generate --symlink --relative FooBar
+# Launch PHP server with web folder as root
+php -S 0.0.0.0:8080 -t web vendor/roadiz/roadiz/conf/router.php
+```
+
+If you want to use PHP internal server, make sure you have installed all required
+PHP extensions and that you have a database server:
+
+- You can use a local MySQL/MariaDB server
+- Or use a SQLite3 database, just use `../app/conf/database.db3` path during install.
+
+> PHP web server was designed to aid application development. It may also be useful for testing purposes or for application demonstrations that are run in controlled environments. It is not intended to be a full-featured web server. It should not be used on a public network.
+
+## Use Mailhog to catch outgoing emails
+
+Contrary to *Vagrant*, using PHP built-in server does not provide any additional tool such as *Mailcatcher* or *Apache Solr*.
+You can setup [Mailhog](https://github.com/mailhog/MailHog) to catch outgoing emails in a clean web interface.
+
+On *macOS*, use *HomeBrew*: `brew update && brew install mailhog`, then configure your PHP `sendmail_path` to 
+use it. 
+

developer/themes/using_twig.rst

@@ -10,30 +10,25 @@ Using Twig
 
 When you use :ref:`Dynamic routing <dynamic-routing>` within your theme, Roadiz will automatically assign some variables for you.
 
+* **cms_version** — [string]
+* **cms_prefix** — [string]
 * **request** — [object] Symfony request object which contains useful data such as current URI or GET parameters
 * **head**
     * **ajax** — [boolean] Tells if current request is an Ajax one
-    * **cmsVersion** — [string]
-    * cmsVersionNumber
-    * **cmsBuild** — [string]
     * **devMode** — [boolean]
-    * **baseUrl** — [string] Server base Url. Basically your domain name, port and folder if you didn’t setup Roadiz at you server root
-    * **filesUrl** — [string]
-    * **resourcesUrl** — [string] Your theme ``Resources`` url. Useful to reach your assets.
-    * **ajaxToken** — [string]
     * **universalAnalyticsId** — [string]
     * **useCdn** - [boolean]
-    * **fontToken** — [string]
+    * **baseUrl** — [string] Server base Url. Basically your domain name, port and folder if you didn’t setup Roadiz at you server root
+    * **filesUrl** — [string]
+    * **resourcesUrl** — [string] Your theme ``Resources`` path. Useful to reach your assets.
+    * **absoluteResourcesUrl** — [string] Your theme absolute ``Resources`` url. Useful to reach your assets outside of your website.
 * **session**
-    * **messages** — [array]
     * **id** — [string]
     * **user** — [object]
 * **bags**
     * **settings** — [SettingsBag]
     * **nodeTypes** — [NodeTypesBag]
     * **roles** — [RolesBag]
-* **authorizationChecker** — [object]
-* **tokenStorage** — [object]
 
 There are some more content only available from *FrontendControllers*.
 
@@ -78,6 +73,20 @@ You can of course call objects members within Twig using the *dot* separator.
         {% endfor %}
     </article>
 
+Checking role permissions
+-------------------------
+
+You can use standard Twig ``is_granted`` method to check if current authenticated user can
+access resources according to Roadiz *ROLES*.
+
+.. code-block:: html+jinja
+
+    {% if is_granted('ROLE_ACCESS_TAGS') %}
+    <div class="tags">
+        User can access tags
+    </div>
+    {% endif %}
+
 Generating paths and url
 ------------------------
 

stable-req.txt

@@ -0,0 +1,22 @@
+alabaster==0.7.10
+Babel==2.5.1
+certifi==2017.11.5
+chardet==3.0.4
+CommonMark==0.5.4
+docutils==0.14
+idna==2.6
+imagesize==0.7.1
+Jinja2==2.10
+MarkupSafe==1.0
+Pygments==2.2.0
+pytz==2017.3
+recommonmark==0.4.0
+requests==2.18.4
+six==1.11.0
+snowballstemmer==1.2.1
+Sphinx==1.6.5
+sphinx-rtd-theme==0.2.4
+sphinxcontrib-websupport==1.0.1
+urllib3==1.22
+
+git+https://github.com/jhermann/pygments-markdown-lexer.git#egg=pygments-markdown-lexer==pygments-markdown-lexer