diff --git a/daux.phar b/daux.phar index 06d7343..9f6a55c 100755 Binary files a/daux.phar and b/daux.phar differ diff --git a/docs/05_Configuration/Confluence_upload.md b/docs/05_Configuration/Confluence_upload.md index 269267e..2bbabc3 100644 --- a/docs/05_Configuration/Confluence_upload.md +++ b/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. diff --git a/libs/Format/Confluence/Api.php b/libs/Format/Confluence/Api.php index 403fa04..fa434a7 100644 --- a/libs/Format/Confluence/Api.php +++ b/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) { diff --git a/libs/Format/Confluence/Publisher.php b/libs/Format/Confluence/Publisher.php index 4796823..c5e79df 100644 --- a/libs/Format/Confluence/Publisher.php +++ b/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']); - $published = null; - foreach ($pages as $page) { - if ($page['title'] == $tree['title']) { - $published = $page; - break; + if (array_key_exists('ancestor_id', $this->confluence)) { + $pages = $this->client->getList($this->confluence['ancestor_id']); + $published = null; + foreach ($pages as $page) { + if ($page['title'] == $tree['title']) { + $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) { - return false; + // This is configurable with `update_threshold` + $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