# 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](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).

## Usage

You can install the module via [nuget](https://www.nuget.org).

```
Install-Module victorykit.PSConfluencePublisher
```

Alternatively, you can import the module from source. In order to do that, 
clone the 
[Git repository](https://bitbucket.org/victorykit/psconfluencepublisher/src)
, 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](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.3#debugpreference)
to `Continue`, or `Inquire` in your shell's *Global* scope.

## Testing

This program requires [Pester](https://pester.dev/) to execute it's test suite.

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