victorykit.PSConfluencePublisher 1.0.0

PSConfluencePublisher

This program is a standalone publisher component for the victorykit-xconfluencebuilder Sphinx extension.

It consumes, a JSON-formatted manifest of a Sphinx build dump generated by the sphinxcontrib.xconfluencebuilder and unidirectionally synchronizes pages, page ancestry, and attachments.

Publishing is supported via the Confluence Server REST API through Personal Access Token (PAT) authorization.

(Interchange) Manifest

The manifest consists of a Pages manifest and an Attachments manifest, which store metadata on pages and attachments. Even though the Pages manifests (represented as array object) is expected to have the appropriate order for publishing, where the oldest ancestral generation of pages is published before the youngest, this isn't trusted and the pages manifest is ordered in-place, through a Hoare partitioned Quick-Sort via the Optimize-PagesManifest function.

The manifest is treated as read/write and used for storing additional metadata to reduce the amount of remote data retrieval. This includes hashing of page and attachments content in addition to tracking publishing versions and remote ids. Through a JSONSchema, it is made sure that the manifest stays consistent for interchange with the original manifest producer system (victorykit-xconfluencebuilder).

Usage

You will be able to install the module via nuget. This however is not yet possible.

Install-Module victorykit.PSConfluencePublisher

Alternatively, you can import the module from source. In order to do that, clone the Git repository , change into the directory and import it.

PS> git clone git@bitbucket.org:victorykit/psconfluencepublisher.git

PS> # universal import statement compatible with PowerShell Core & Desktop
PS> Import-Module (Join-Path 'tools'
                             '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.

Register-PersonalAccessToken `
    -Host 'confluence.contoso.com' `
    -Token '123456789123456789'

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.

Test-Connection confluence.contoso.com

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.

Publish-Dump `
    -Url 'https://confluence.contoso.com/display/TIARA/Testitest' `
    -DumpIndex build/docs/confluence.out/data.json

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

Debugging

To display debug messages, set $DebugPreference to Continue, or Inquire in your shell's Global scope.

Testing

This program requires Pester to execute it's test suite.

You can execute the following from within a PowerShell session.

PS> Invoke-Pester tools/*.Tests.ps1 -Show 'All'

or the following, from within a POSIX shell and PowerShell Core being present:

$ pwsh -c "Invoke-Pester tools/*.Tests.ps1 -Show 'All'"