# PSConfluencePublisher

This program is a standalone publisher component for the 
[victorykit-xconfluencebuilder](https://bitbucket.org/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](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).

## (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](https://www.nuget.org). 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](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 '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](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.

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'"``