From 5fce02eb360c45e77f0b1924891f4ab7ee5ecbfc Mon Sep 17 00:00:00 2001 From: "Rodweil, Theodor" Date: Mon, 14 Aug 2023 05:06:58 +0200 Subject: [PATCH] chore: update README --- README.md | 123 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 94 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index beb1613..d9645ee 100755 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This program is a standalone publisher component for the [victorykit-xconfluencebuilder](https://bitbucket.org/victorykit/xconfluencebuilder) -Sphinx extension. +Sphinx extension. It consumes, a JSON-formatted manifest of a *Sphinx build* dump generated by the `victorykit-xconfluencebuilder` and unidirectionally synchronizes @@ -51,46 +51,109 @@ PS> # universal import statement compatible with PowerShell Core & Desktop PS> Import-Module "src/PSConfluencePublisher.psd1" ``` -Next, register your personal access token for your Confluence server instance. -The token is stored as a *SecureString* type within the scope of the responsible -ested module (``PersonalAccessToken``). It is expected to have one Personal -Access Token per Confluence instance, per PowerShell session. +An implementation reference is provided through `samples/default`. + +You will need the hostname (or IP address) of a Confluence instance, a Personal +Access Token (PAT) and the name of a space. + +The reference implementation uses manifest data generated by the sample +reference implementation of *xconfluencebuilder*, which are 2 (ancestraly +related) pages with 2 attachments (JPEG images, more importantly JPEG cat +images). + +To execute the sample reference implementation, run +`pwsh samples/default/run.ps1` ``` -Register-PersonalAccessToken ` - -Host 'confluence.contoso.com' ` - -Token '123456789123456789' +$ pwsh samples/default/run.ps1 \ + -Hostname 'confluence.contoso.com' \ + -Space 'MS' \ + -PersonalAccessToken `THISISNOTAREALTOKEN` +initializing manifest... +DEBUG: Initialize-Manifest: loading manifest... +DEBUG: Initialize-Manifest: creating pages manifest index... +DEBUG: Initialize-Manifest: creating ancestral page generation cache... +DEBUG: Initialize-Manifest: sorting pages manifest... +DEBUG: Initialize-Manifest: recreating pages manifest index... +DEBUG: Initialize-Manifest: creating attachments manifest index... +initializing and testing connectivity... +Verified connectivity (confluence.contoso.com). +fetching pages metadata... +DEBUG: Get-PageMetadata: `Default Sample~`: no remote, using (partial) local +DEBUG: Get-PageMetadata: `Cats`: no remote, using (partial) local +publishing pages (2)... +Update-Page: `Default Sample~`: unknown page id. Skipping. +Update-Page: `Cats`: unknown page id. Skipping. +New-Page: `Default Sample~`: creating +New-Page: `Cats`: creating +fetching attachments metadata... +DEBUG: Get-AttachmentMetadata: `pexels-just-a-couple-photos-3777622.jpg`: no remote, using (partial) local +DEBUG: Get-AttachmentMetadata: `pexels-sami-aksu-14356302.jpg`: no remote, using (partial) local +DEBUG: Get-AttachmentMetadata: `objects.inv`: no remote, using (partial) local +publishing attachments (3)... +Update-Attachment: `pexels-just-a-couple-photos-3777622.jpg`: unknown attachment id. Skipping. +Update-Attachment: `pexels-sami-aksu-14356302.jpg`: unknown attachment id. Skipping. +Update-Attachment: `objects.inv`: unknown attachment id. Skipping. +New-Attachment: `pexels-just-a-couple-photos-3777622.jpg`: creating +New-Attachment: `pexels-sami-aksu-14356302.jpg`: creating +New-Attachment: `objects.inv`: creating +dumping manifest to filesystem... ``` -Optionally, you may test the connectivity to your Confluence instance. The test -will try to retrieve your user profile, in order to determine whether the PAT -authenticates, since an invalid PAT may results in anonymous authentication, -that does not return a fault HTTP status code for some REST API functions. +On the next invocation, only changed content will be updated: ``` -Test-Connection confluence.contoso.com +$ pwsh samples/default/run.ps1 \ + -Hostname 'confluence.contoso.com' \ + -Space 'MS' \ + -PersonalAccessToken `THISISNOTAREALTOKEN` +initializing manifest... +DEBUG: Initialize-Manifest: loading manifest... +DEBUG: Initialize-Manifest: creating pages manifest index... +DEBUG: Initialize-Manifest: creating ancestral page generation cache... +DEBUG: Initialize-Manifest: sorting pages manifest... +DEBUG: Initialize-Manifest: recreating pages manifest index... +DEBUG: Initialize-Manifest: creating attachments manifest index... +initializing and testing connectivity... +Verified connectivity (confluence.contoso.com). +fetching pages metadata... +DEBUG: Get-PageMeta: `Default Sample~`: using locally cached metadata (789703435) +DEBUG: Get-PageMeta: `Cats`: using locally cached metadata (789703436) +publishing pages (2)... +DEBUG: Update-Page: `Default Sample~`: skipping, no content changes +DEBUG: Update-Page: `Cats`: skipping, no content changes +DEBUG: New-Page: `Default Sample~`: skipping, already published (789703435) +DEBUG: New-Page: `Cats`: skipping, already published (789703436) +fetching attachments metadata... +DEBUG: Get-AttachmentMeta: `pexels-just-a-couple-photos-3777622.jpg`: using locally cached metadata (789703437) +DEBUG: Get-AttachmentMeta: `pexels-sami-aksu-14356302.jpg`: using locally cached metadata (789703438) +DEBUG: Get-AttachmentMeta: `objects.inv`: using locally cached metadata (789703439) +publishing attachments (3)... +DEBUG: Update-Attachment: `pexels-just-a-couple-photos-3777622.jpg`: skipping, no content changes +DEBUG: Update-Attachment: `pexels-sami-aksu-14356302.jpg`: skipping, no content changes +DEBUG: Update-Attachment: `objects.inv`: skipping, no content changes +DEBUG: New-Attachment: `pexels-just-a-couple-photos-3777622.jpg`: skipping, already published (789703437) +DEBUG: New-Attachment: `pexels-sami-aksu-14356302.jpg`: skipping, already published (789703438) +DEBUG: New-Attachment: `objects.inv`: skipping, already published (789703439) +dumping manifest to filesystem... ``` -Now you may publish by supplying the URL of the root Confluence page -you want to publish to, in addition to the location of the local dump manifest. -Make sure to use the full URL, with the same hostname as the one you used to -register your personal access token. +Content can still be forcefully updated by supplying a ``-Force`` switch: ``` -Publish-Dump ` - -Url 'https://confluence.contoso.com/display/TIARA/Testitest' ` - -DumpIndex build/docs/confluence.out/data.json +$ pwsh samples/default/run.ps1 \ + -Hostname 'confluence.contoso.com' \ + -Space 'MS' \ + -PersonalAccessToken `THISISNOTAREALTOKEN` \ + -Force ``` -The manifest MUST be writable, where it is then used to cache the publishing -status of each page and attachment. -You may publish a single page, which however requires it's direct ancestral page -to exist. -``` -Publish-Page -``` + +For the current moment, the top-level/root page will be applied to the root of +the Confluence space. Manually move the page (as necessary) after initial +publishing, recurring publishments will not require you to do so. ## Compatibility @@ -101,12 +164,14 @@ This program is compatible with the following Microsoft PowerShell runtimes: ## Runtime Dependencies -This program has no runtime dependencies. +This program has no runtime dependencies and is purely written in the PowerShell +scripting language, with some built-in dependencies towards .NET Core 2 (present +in all PowerShell editions). On PowerShell Desktop, however, it is necessary to obtain the `Microsoft.PowerShell.Utility` module for JSON schema verification of the manifest. Whether that's possible for PowerShell Desktop; We do not know. -Should the aforementioned module not be present, JSON validation is skipped. +Should the aforementioned module not be present, JSON validation is disabled. ## Debugging