uapv/uapvhelpplugin

Plugin Symfony pour afficher automatiquement une aide au format Markdown sur les pages d'une application

uapvHelpPlugin

Features

uapvHelpPlugin displays a link to the documentation of your symfony actions when it exists. The Markdown syntax is used to help you write theses files in an easy-to-read and easy-to-write way. Theses files are also parsed with PHP to allow you to use any symfony helpers you want.

uapvHelpPlugin also use the symfony cache to prevent unneeded markown parsing. Don't forget to use 'symfony cc' whenever you modify the documentation files.

How to install ?

1. Get the sources

   git clone git://github.com/UAPV/uapvHelpPlugin.git plugins/uapvHelpPlugin symfony plugin:publish-assets

2. Enable the plugin by adding this line to the 'setup()' method in your 'config/ProjectConfiguration.class.php' file :

   $this->enablePlugins('uapvHelpPlugin');
   

3. In your setting.yml :

   • Enable the uapvHelpPage module :

     enabled_modules: [default, uapvHelpPage]
     

   • Add 'AutoHelp' to the standard_helpers to avoid writing "use_helper('AutoHelp')" everywhere

     standard_helpers: [Partial, Cache, AutoHelp]
     

4. Use this helper in your layout.php :

   <?php echo help_link () ?>
   

How to use ?

1. Create a 'doc' directory in the application you want to document, for example 'apps/frontend/doc'

2. Create a 'fr' directory to add a french documentation, for example 'apps/frontend/doc/fr'

3. To document the index action, create the file 'app/frontend/modules/myModule/doc/fr/index.mkd'

Advanced use

Enabling a fall back documentation

If you want to display a documentation link on the page even if there is no specific help for the requested module/action, create the file 'apps/frontend/doc/fr/index.mkd'.

Adding links to other documentation pages in your markdown files

Use this helper function in your markdown files to add a link to the 'list' action of the 'pages' module :

Hey, have a look <?php echo link_to_help ('here for more details', 'pages/list'); ?>o

You can also link to the user documentation from your Symfony views :

<?php echo link_to_help ('Follow this link to learn more about this feature', 'pages/list') ?>

Specifying the default language

uapvHelpPlugin will use the 'Accept-Language' request header to find the correct documentation page to use for your visitors. However, if this page does not exist or if there is no 'Accept-Language' header, uapvHelpPlugin will use the 'default_culture' parameter defined in your 'i18n.yml' configuration. Make sure it is correct.

Linking to a specific documentation anchor

To add an anchor in your documentation follow the syntax described here :

Example :

Header 1            {#my_anchor_id}
========

Then use this link helper :

<?php echo link_to_help ('pages/list#my_anchor_id') ?>

Adding a header and footer on every page

Add a file named "_header.mkd" or "_footer.mkd" in your doc/[lang]/ directory. This file can use markdown syntax.

Redirecting a user to an external documentation

If some or all of your document are already stored somewhere else, you will need can add exceptions by editing your app.yml

all:
  help:
    external:
      ";account/*/edit;" : http://dosi.univ-avignon.fr/foobar
      ";admin/.*;" : https://github.com/UAPV/uapvHelpPlugin/blob/master/README.mkd
      ";.*;" : http://dosi.univ-avignon.fr

The 'app_help_external' parameter is an array of URL corresponding to patterns (compatibles with 'preg_match()'). This patterns will be compared with the current PATH_INFO url. If there is the match and if the user tries to open the help for the current page, he will be redirected to the url associated to the pattern.

Adding documentation assets

You may need to add images or link static files on your documentation. To do this, place all your files along with your markdown documentation and run :

symfony doc:publish-assets // __NOT IMPLEMENTED YET__

Then use the help_public_path() or help_image_tag() helper to display images in your documentation. For example, if you have 'image.png' in the same directory as your markdown documentation use a relative URL.

![my image](<?php echo help_public_path ('image.png') ?>)
// equivalent to
<?php echo help_image_tag('image.png') ?>

You can also use absolute URL, ex: /user/create_form.png

Creating a documentation index

??

Future improvements

• documentation search form
• documentation index
• automatic cache invalidation