PSConfluencePublisher

This program is a standalone publisher component for the sphinxcontrib.confluencebuilder 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.

Usage

You can install the module via nuget.

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 'PSConfluencePublisher'
                             'PSConfluencePublisher.psd1')

Next, register your personal access token for your Confluence server instance. The token is stored as a SecureString within the Script scope.

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 simply results in anonymous authentication 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 may 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 ancestor 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 PSConfluencePublisher/*.Tests.ps1 -Show 'All'

However the test suite still requires optimization towards execution, as Pester requires a certain setup for tests of nested modules to work. The Force switch does not work as expected on the Import-Module cmdlet (within the BeforeAll script blocks). Therefore it is advised to wrap the Invoke-Pester as follows so that the global scope gets teared down after execution.

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