123 lines
4.7 KiB
Markdown
Executable file
123 lines
4.7 KiB
Markdown
Executable file
# 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).
|
|
|
|
## (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
|
|
(```sphinxcontrib.xconfluencebuilder``).
|
|
|
|
## 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* 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 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'"``
|
|
|
|
There currently is an issue with the invocation of the test suites (see
|
|
[Pester Issue #2386](https://github.com/pester/Pester/issues/2386)), where
|
|
some tests fail, if ran via the wildcard discovery.
|
|
|
|
Execute the following from within a PowerShell session to temporarily circumvent
|
|
this problem:
|
|
|
|
``$ pwsh -c 'Get-ChildItem PSConfluencePublisher/*.Tests.ps1 | ForEach {pwsh -c Invoke-Pester (Resolve-Path -Relative $_)}'``
|