chore: update README
This commit is contained in:
Rodweil, Theodor
parent
4b458df7c1
commit
5fce02eb36
1 changed files with 94 additions and 29 deletions
123
README.md
123
README.md
|
|
@ -2,7 +2,7 @@
|
||||||
|
|
||||||
This program is a standalone publisher component for the
|
This program is a standalone publisher component for the
|
||||||
[victorykit-xconfluencebuilder](https://bitbucket.org/victorykit/xconfluencebuilder)
|
[victorykit-xconfluencebuilder](https://bitbucket.org/victorykit/xconfluencebuilder)
|
||||||
Sphinx extension.
|
Sphinx extension.
|
||||||
|
|
||||||
It consumes, a JSON-formatted manifest of a *Sphinx build* dump generated by
|
It consumes, a JSON-formatted manifest of a *Sphinx build* dump generated by
|
||||||
the `victorykit-xconfluencebuilder` and unidirectionally synchronizes
|
the `victorykit-xconfluencebuilder` and unidirectionally synchronizes
|
||||||
|
|
@ -51,46 +51,109 @@ PS> # universal import statement compatible with PowerShell Core & Desktop
|
||||||
PS> Import-Module "src/PSConfluencePublisher.psd1"
|
PS> Import-Module "src/PSConfluencePublisher.psd1"
|
||||||
```
|
```
|
||||||
|
|
||||||
Next, register your personal access token for your Confluence server instance.
|
An implementation reference is provided through `samples/default`.
|
||||||
The token is stored as a *SecureString* type within the scope of the responsible
|
|
||||||
ested module (``PersonalAccessToken``). It is expected to have one Personal
|
You will need the hostname (or IP address) of a Confluence instance, a Personal
|
||||||
Access Token per Confluence instance, per PowerShell session.
|
Access Token (PAT) and the name of a space.
|
||||||
|
|
||||||
|
The reference implementation uses manifest data generated by the sample
|
||||||
|
reference implementation of *xconfluencebuilder*, which are 2 (ancestraly
|
||||||
|
related) pages with 2 attachments (JPEG images, more importantly JPEG cat
|
||||||
|
images).
|
||||||
|
|
||||||
|
To execute the sample reference implementation, run
|
||||||
|
`pwsh samples/default/run.ps1`
|
||||||
|
|
||||||
```
|
```
|
||||||
Register-PersonalAccessToken `
|
$ pwsh samples/default/run.ps1 \
|
||||||
-Host 'confluence.contoso.com' `
|
-Hostname 'confluence.contoso.com' \
|
||||||
-Token '123456789123456789'
|
-Space 'MS' \
|
||||||
|
-PersonalAccessToken `THISISNOTAREALTOKEN`
|
||||||
|
initializing manifest...
|
||||||
|
DEBUG: Initialize-Manifest: loading manifest...
|
||||||
|
DEBUG: Initialize-Manifest: creating pages manifest index...
|
||||||
|
DEBUG: Initialize-Manifest: creating ancestral page generation cache...
|
||||||
|
DEBUG: Initialize-Manifest: sorting pages manifest...
|
||||||
|
DEBUG: Initialize-Manifest: recreating pages manifest index...
|
||||||
|
DEBUG: Initialize-Manifest: creating attachments manifest index...
|
||||||
|
initializing and testing connectivity...
|
||||||
|
Verified connectivity (confluence.contoso.com).
|
||||||
|
fetching pages metadata...
|
||||||
|
DEBUG: Get-PageMetadata: `Default Sample~`: no remote, using (partial) local
|
||||||
|
DEBUG: Get-PageMetadata: `Cats`: no remote, using (partial) local
|
||||||
|
publishing pages (2)...
|
||||||
|
Update-Page: `Default Sample~`: unknown page id. Skipping.
|
||||||
|
Update-Page: `Cats`: unknown page id. Skipping.
|
||||||
|
New-Page: `Default Sample~`: creating
|
||||||
|
New-Page: `Cats`: creating
|
||||||
|
fetching attachments metadata...
|
||||||
|
DEBUG: Get-AttachmentMetadata: `pexels-just-a-couple-photos-3777622.jpg`: no remote, using (partial) local
|
||||||
|
DEBUG: Get-AttachmentMetadata: `pexels-sami-aksu-14356302.jpg`: no remote, using (partial) local
|
||||||
|
DEBUG: Get-AttachmentMetadata: `objects.inv`: no remote, using (partial) local
|
||||||
|
publishing attachments (3)...
|
||||||
|
Update-Attachment: `pexels-just-a-couple-photos-3777622.jpg`: unknown attachment id. Skipping.
|
||||||
|
Update-Attachment: `pexels-sami-aksu-14356302.jpg`: unknown attachment id. Skipping.
|
||||||
|
Update-Attachment: `objects.inv`: unknown attachment id. Skipping.
|
||||||
|
New-Attachment: `pexels-just-a-couple-photos-3777622.jpg`: creating
|
||||||
|
New-Attachment: `pexels-sami-aksu-14356302.jpg`: creating
|
||||||
|
New-Attachment: `objects.inv`: creating
|
||||||
|
dumping manifest to filesystem...
|
||||||
```
|
```
|
||||||
|
|
||||||
Optionally, you may test the connectivity to your Confluence instance. The test
|
On the next invocation, only changed content will be updated:
|
||||||
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
|
$ pwsh samples/default/run.ps1 \
|
||||||
|
-Hostname 'confluence.contoso.com' \
|
||||||
|
-Space 'MS' \
|
||||||
|
-PersonalAccessToken `THISISNOTAREALTOKEN`
|
||||||
|
initializing manifest...
|
||||||
|
DEBUG: Initialize-Manifest: loading manifest...
|
||||||
|
DEBUG: Initialize-Manifest: creating pages manifest index...
|
||||||
|
DEBUG: Initialize-Manifest: creating ancestral page generation cache...
|
||||||
|
DEBUG: Initialize-Manifest: sorting pages manifest...
|
||||||
|
DEBUG: Initialize-Manifest: recreating pages manifest index...
|
||||||
|
DEBUG: Initialize-Manifest: creating attachments manifest index...
|
||||||
|
initializing and testing connectivity...
|
||||||
|
Verified connectivity (confluence.contoso.com).
|
||||||
|
fetching pages metadata...
|
||||||
|
DEBUG: Get-PageMeta: `Default Sample~`: using locally cached metadata (789703435)
|
||||||
|
DEBUG: Get-PageMeta: `Cats`: using locally cached metadata (789703436)
|
||||||
|
publishing pages (2)...
|
||||||
|
DEBUG: Update-Page: `Default Sample~`: skipping, no content changes
|
||||||
|
DEBUG: Update-Page: `Cats`: skipping, no content changes
|
||||||
|
DEBUG: New-Page: `Default Sample~`: skipping, already published (789703435)
|
||||||
|
DEBUG: New-Page: `Cats`: skipping, already published (789703436)
|
||||||
|
fetching attachments metadata...
|
||||||
|
DEBUG: Get-AttachmentMeta: `pexels-just-a-couple-photos-3777622.jpg`: using locally cached metadata (789703437)
|
||||||
|
DEBUG: Get-AttachmentMeta: `pexels-sami-aksu-14356302.jpg`: using locally cached metadata (789703438)
|
||||||
|
DEBUG: Get-AttachmentMeta: `objects.inv`: using locally cached metadata (789703439)
|
||||||
|
publishing attachments (3)...
|
||||||
|
DEBUG: Update-Attachment: `pexels-just-a-couple-photos-3777622.jpg`: skipping, no content changes
|
||||||
|
DEBUG: Update-Attachment: `pexels-sami-aksu-14356302.jpg`: skipping, no content changes
|
||||||
|
DEBUG: Update-Attachment: `objects.inv`: skipping, no content changes
|
||||||
|
DEBUG: New-Attachment: `pexels-just-a-couple-photos-3777622.jpg`: skipping, already published (789703437)
|
||||||
|
DEBUG: New-Attachment: `pexels-sami-aksu-14356302.jpg`: skipping, already published (789703438)
|
||||||
|
DEBUG: New-Attachment: `objects.inv`: skipping, already published (789703439)
|
||||||
|
dumping manifest to filesystem...
|
||||||
```
|
```
|
||||||
|
|
||||||
Now you may publish by supplying the URL of the root Confluence page
|
Content can still be forcefully updated by supplying a ``-Force`` switch:
|
||||||
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 `
|
$ pwsh samples/default/run.ps1 \
|
||||||
-Url 'https://confluence.contoso.com/display/TIARA/Testitest' `
|
-Hostname 'confluence.contoso.com' \
|
||||||
-DumpIndex build/docs/confluence.out/data.json
|
-Space 'MS' \
|
||||||
|
-PersonalAccessToken `THISISNOTAREALTOKEN` \
|
||||||
|
-Force
|
||||||
```
|
```
|
||||||
|
|
||||||
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
|
For the current moment, the top-level/root page will be applied to the root of
|
||||||
```
|
the Confluence space. Manually move the page (as necessary) after initial
|
||||||
|
publishing, recurring publishments will not require you to do so.
|
||||||
|
|
||||||
## Compatibility
|
## Compatibility
|
||||||
|
|
||||||
|
|
@ -101,12 +164,14 @@ This program is compatible with the following Microsoft PowerShell runtimes:
|
||||||
|
|
||||||
## Runtime Dependencies
|
## Runtime Dependencies
|
||||||
|
|
||||||
This program has no runtime dependencies.
|
This program has no runtime dependencies and is purely written in the PowerShell
|
||||||
|
scripting language, with some built-in dependencies towards .NET Core 2 (present
|
||||||
|
in all PowerShell editions).
|
||||||
|
|
||||||
On PowerShell Desktop, however, it is necessary to obtain the
|
On PowerShell Desktop, however, it is necessary to obtain the
|
||||||
`Microsoft.PowerShell.Utility` module for JSON schema verification of the
|
`Microsoft.PowerShell.Utility` module for JSON schema verification of the
|
||||||
manifest. Whether that's possible for PowerShell Desktop; We do not know.
|
manifest. Whether that's possible for PowerShell Desktop; We do not know.
|
||||||
Should the aforementioned module not be present, JSON validation is skipped.
|
Should the aforementioned module not be present, JSON validation is disabled.
|
||||||
|
|
||||||
## Debugging
|
## Debugging
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue