[Confluence] Add options on the update_threshold, and ability to specify a root_id instead of ancestor_id

docs/05_Configuration/Confluence_upload.md

@@ -27,6 +27,10 @@ You can obtain the `ancestor_id` id by editing the page you want to define as a
 }
 ```
 
+You can also provide a `root_id` instead of an `ancestor_id` in this case, you specify the id as the homepage of your documentation.
+
+You can use that when you're uploading your documentation to the root of a Confluence Space or if your page already exists.
+
 ## Prefix
 Because confluence can't have two pages with the same name in a space, I recommend you define a prefix for your pages.
 
@@ -35,3 +39,32 @@ Because confluence can't have two pages with the same name in a space, I recomme
 	"confluence": { "prefix": "[DAUX]" }
 }
 ```
+
+## Update threshold
+To make the upload quicker, we try to determine if a page changed or not, first with a strict comparison and if it's not completely identical, we compute the difference.
+
+```json
+{
+	"confluence": { "update_threshold": 1 }
+}
+```
+
+If you set `update_threshold` to 1, it will upload only if the page has more than 1% difference with the previous one.
+
+By default the threshold is 2%.
+
+Setting the value to `0` disables the feature altogether.
+
+
+## Delete old pages
+When a page is renamed, there is no way to tell it was renamed, so when uploading to Confluence, the page will be uploaded and the old page will stay here.
+
+By default, it will inform you that some pages aren't needed anymore and you can delete them by hand.
+
+```json
+{
+	"confluence": { "delete": true }
+}
+```
+
+By setting `delete` to `true` (or running `daux.phar` with the `--delete` flag) you tell the generator that it can safely delete the pages.

libs/Format/Confluence/Api.php

@@ -76,6 +76,31 @@ class Api
         return new BadResponseException($message, $request, $response, $e->getPrevious());
     }
 
+    public function getPage($id)
+    {
+       $url = "content/$id?expand=ancestors,version,body.storage";
+
+        try {
+            $result = $this->getClient()->get($url)->json();
+        } catch (BadResponseException $e) {
+            throw $this->handleError($e);
+        }
+
+        $ancestor_id = null;
+        if (array_key_exists('ancestors', $result) && count($result['ancestors'])) {
+            $ancestor_page = end($result['ancestors']); // We need the direct parent
+            $ancestor_id = $ancestor_page['id'];
+        }
+
+        return [
+            "id" => $result['id'],
+            "ancestor_id" => $ancestor_id,
+            "title" => $result['title'],
+            "version" => $result['version']['number'],
+            "content" => $result['body']['storage']['value'],
+        ];
+    }
+
     /**
      * Get a list of pages
      *
@@ -137,11 +162,14 @@ class Api
         $body = [
             'type' => 'page',
             'space' => ['key' => $this->space],
-            'ancestors' => [['type' => 'page', 'id' => $parent_id]],
             'title' => $title,
             'body' => ['storage' => ['value' => $content, 'representation' => 'storage']]
         ];
 
+        if ($parent_id) {
+            $body['ancestors'] = [['type' => 'page', 'id' => $parent_id]];
+        }
+
         try {
             $response = $this->getClient()->post('content', ['json' => $body])->json();
         } catch (BadResponseException $e) {
@@ -163,12 +191,15 @@ class Api
         $body = [
             'type' => 'page',
             'space' => ['key' => $this->space],
-            'ancestors' => [['type' => 'page', 'id' => $parent_id]],
             'version' => ['number' => $newVersion, "minorEdit" => true],
             'title' => $title,
             'body' => ['storage' => ['value' => $content, 'representation' => 'storage']]
         ];
 
+        if ($parent_id) {
+            $body['ancestors'] = [['type' => 'page', 'id' => $parent_id]];
+        }
+
         try {
             $this->getClient()->put("content/$page_id", ['json' => $body])->json();
         } catch (BadResponseException $e) {

libs/Format/Confluence/Publisher.php

@@ -54,16 +54,26 @@ class Publisher
 
     public function publish(array $tree)
     {
+
         echo "Finding Root Page...\n";
-        $pages = $this->client->getList($this->confluence['ancestor_id']);
+        if (array_key_exists('ancestor_id', $this->confluence)) {
-        $published = null;
+            $pages = $this->client->getList($this->confluence['ancestor_id']);
-        foreach ($pages as $page) {
+            $published = null;
-            if ($page['title'] == $tree['title']) {
+            foreach ($pages as $page) {
-                $published = $page;
+                if ($page['title'] == $tree['title']) {
-                break;
+                    $published = $page;
+                    break;
+                }
             }
+        } elseif (array_key_exists('root_id', $this->confluence)) {
+            $published = $this->client->getPage($this->confluence['root_id']);
+            $this->confluence['ancestor_id'] = $published['ancestor_id'];
+        } else {
+            throw new \RuntimeException("You must at least specify a `root_id` or `ancestor_id` in your confluence configuration.");
         }
 
+
+
         $this->run(
             "Getting already published pages...",
             function() use (&$published) {
@@ -104,6 +114,7 @@ class Publisher
     {
         echo "- " . $this->niceTitle($entry['file']->getUrl()) . "\n";
         $published['version'] = 1;
+        $published['title'] = $entry['title'];
         $published['id'] = $this->client->createPage($parent_id, $entry['title'], "The content will come very soon !");
 
         return $published;
@@ -113,6 +124,7 @@ class Publisher
     {
         echo "- " . $entry['title'] . "\n";
         $published['version'] = 1;
+        $published['title'] = $entry['title'];
         $published['id'] = $this->client->createPage($parent_id, $entry['title'], "");
 
         return $published;
@@ -220,13 +232,20 @@ class Publisher
             return false;
         }
 
-        similar_text($trimmed_local, $trimmed_distant, $percent);
-
         // I consider that if the files are 98% identical you
         // don't need to update. This will work for false positives.
         // But sadly will miss if it's just a typo update
-        if ($percent >= 98) {
+        // This is configurable with `update_threshold`
-            return false;
+        $threshold = 98;
+        if (array_key_exists('update_threshold', $this->confluence)) {
+            $threshold = 100 - $this->confluence['update_threshold'];
+        }
+
+        if ($threshold < 100) {
+            similar_text($trimmed_local, $trimmed_distant, $percent);
+            if ($percent > $threshold) {
+                return false;
+            }
         }
 
         //DEBUG