init

README.md

@@ -0,0 +1,85 @@
+# 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'``