Merge pull request #52 from piwik/review/cli

#22 Reviewed "Piwik on the Command Line"

app/helpers/Content/Category/DevelopCategory.php

@@ -35,13 +35,14 @@ public function getItems()
                 new Guide('piwiks-extensibility-points'),
             ]),
             new Guide('mvc-in-piwik'),
-            new EmptySubCategory('User Interface', [
+            new EmptySubCategory('Web Interface', [
                 new Guide('pages'),
                 new Guide('menus'),
                 new Guide('widgets'),
                 new Guide('working-with-piwiks-ui'),
                 new Guide('visualizing-report-data'),
             ]),
+            new Guide('piwik-on-the-command-line'),
             new Guide('piwik-configuration'),
             new Guide('persistence-and-the-mysql-backend'),
             new EmptySubCategory('Security', [
@@ -52,7 +53,6 @@ public function getItems()
             new Guide('tests'),
             new Guide('piwiks-reporting-api'),
             new Guide('scheduled-tasks'),
-            new Guide('piwik-on-the-command-line'),
             new EmptySubCategory('Piwik Core development', [
                 new Guide('contributing-to-piwik-core'),
                 new Guide('core-team-workflow'),

docs/piwik-on-the-command-line.md

@@ -1,73 +1,60 @@
 ---
 category: Develop
 ---
-# Piwik on the Command Line
+# Command Line Interface
 
-<!-- Meta (to be deleted)
-Purpose:
-- describe how command line tool works,
-- describe each console command,
-- describe how plugin devs can create their own console commands (describe conventions)
+As explained in the [*How Piwik Works* guide](http://developer.piwik.org/guides/how-piwik-works#interfaces), Piwik can be used through several interfaces, the command line being one of them.
 
-Audience: 
+The CLI console lets user run **commands** defined by plugins. Those commands can be used to perform maintenance, to monitor the application, to ease development…
 
-Expected Result: 
+## The `console` tool
 
-Notes: 
+To use Piwik on the command line, all you need to do is run the console tool. The tool is a script located in Piwik's root directory and called `console`. You can run it with the command:
 
-What's missing? (stuff in my list that was not in when I wrote the 1st draft)
-- TODO: can probably get rid of this guide, move the info to other guides.
--->
-
-## About this guide
-
-**Read this guide if**
-
-* you'd like to know **how to use a specific command with Piwik's command line tool**
-* you'd like to know **how your plugin can create a new command for the command line tool**
-* you'd like to know more about **how the command line tool works**
-
-**Guide assumptions**
-
-This guide assumes that you:
-
-* can code in PHP,
-* and have installed Piwik (if not read our [Getting Started](/guides/getting-started-part-1) guide)
-
-## The **console** tool
-
-Piwik comes with a special command line tool that can be used to make development easier. The tool is located in Piwik's root directory and is called **console**. You can run it with the command:
-
-    ./console help
+```bash
+./console help
+```
 
 or
 
-    php ./console help
-
-**Libraries Used**
+```bash
+php ./console help
+```
 
-The console app uses the [Symfony Console component](http://symfony.com/doc/current/components/console/introduction.html). It would have been installed when you ran [composer.phar](http://getcomposer.org/) while installing Piwik.
+The Piwik console is built using the [Symfony Console component](http://symfony.com/doc/current/components/console/introduction.html). If you are familiar with Symfony, you should immediately find your way in the Piwik console.
 
 ### Commands
 
-The command line tool currently supports commands that generate empty plugins and plugin files, run git commands, watch Piwik's log output, run tests and deal with Piwik translations.
+The console can be used to run Piwik commands like so:
+
+```bash
+./console <command>
+```
+
+The console contains commands that generate empty plugins and plugin files, run git commands, watch Piwik's log output, run tests, deal with Piwik translations, …
 
 You can view the entire list of commands by running the following command:
 
-    ./console list
+```bash
+./console list
+```
 
 To get more information about a single command (such as what arguments it takes), run the following command:
 
-    ./console help <<command>>
+```bash
+./console help <command>
+```
 
-where `<<command>>` should be replaced with the command you are interested in.
+where `<command>` should be replaced with the command you are interested in.
 
 ## Adding new commands
 
 Plugins can extend the command line tool by creating their own commands. To do so you can use the CLI itself: 
 
-    ./console generate:command --pluginname=MyPlugin
-
-This will create a folder named `Commands` within your plugin, if necessary, along with a PHP file which represents the actual command. You can add an unlimited number of commands using the CLI.
+```bash
+./console generate:command --pluginname=MyPlugin
+```
+
+This will create a folder named `Commands` within your plugin along with a PHP file which represents the actual command. You can add an unlimited number of commands to a plugin.
 
-See the docs for [SymfonyCommand](http://symfony.com/doc/current/components/console/index.html) to learn more about how your command should be coded.
+To learn how you can write your command, read the [Symfony Console documentation](http://symfony.com/doc/current/components/console/index.html).