tiararodney/psconfluencepublisher
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

chore: update README

Browse source
This commit is contained in:
Rodweil, Theodor 2023-08-08 23:31:44 +02:00
parent 338b9cecb2
commit c134776f47
No known key found for this signature in database
GPG key ID: F8BC1B0EB1F9CCF5
1 changed files with 24 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

36
README.md
View file

@ -5,7 +5,7 @@ This program is a standalone publisher component for the
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 ``sphinxcontrib.xconfluencebuilder`` and unidirectionally synchronizes the `victorykit-xconfluencebuilder` and unidirectionally synchronizes
pages, page ancestry, and attachments. pages, page ancestry, and attachments.
Publishing is supported via the Confluence Server REST API through Publishing is supported via the Confluence Server REST API through
@ -18,7 +18,8 @@ store metadata on pages and attachments. Even though the *Pages* manifests
(represented as array object) is expected to have the appropriate order for (represented as array object) is expected to have the appropriate order for
publishing, where the oldest ancestral generation of pages is published before 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, 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. through a Hoare partitioned Quick-Sort via the ``Optimize-PagesManifest``
function.
The manifest is treated as read/write and used for storing additional metadata 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 to reduce the amount of remote data retrieval. This includes hashing of page and
@ -29,11 +30,11 @@ interchange with the original manifest producer system
## Usage ## Usage
You will be able to install the module via [nuget](https://www.nuget.org). This You may install this PowerShell module via
however is not yet possible. [PowerShellGallery](https://www.powershellgallery.com).
``` ```
Install-Module victorykit.PSConfluencePublisher PS > Install-Module victorykit.PSConfluencePublisher
``` ```
Alternatively, you can import the module from source. In order to do that, Alternatively, you can import the module from source. In order to do that,
@ -47,8 +48,7 @@ PS> git clone git@bitbucket.org:victorykit/psconfluencepublisher.git
``` ```
PS> # universal import statement compatible with PowerShell Core & Desktop PS> # universal import statement compatible with PowerShell Core & Desktop
PS> Import-Module (Join-Path 'tools' PS> Import-Module "src/PSConfluencePublisher.psd1"
'PSConfluencePublisher.psd1')
``` ```
Next, register your personal access token for your Confluence server instance. Next, register your personal access token for your Confluence server instance.
@ -98,15 +98,27 @@ 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) [$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. to `Continue`, or `Inquire` in your shell's *Global* scope.
## Static Code Analysis
This program requires
[PSScriptAnalyzer](https://learn.microsoft.com/en-us/powershell/utility-modules/psscriptanalyzer/overview?view=ps-modules)
for static code analysis.
Execute `pwsh scripts/analyze.ps1` to do a static code analysis.
## Testing ## Testing
This program requires [Pester](https://pester.dev/) to execute it's test suite. This program requires [Pester v5](https://pester.dev/) to execute it's test suite.
You can execute the following from within a PowerShell session. Execute `pwsh scripts/test.ps1` to run the entire test suite.
``PS> Invoke-Pester tools/*.Tests.ps1 -Show 'All'`` ## Packaging & Publishing
or the following, from within a POSIX shell and PowerShell Core being present: This program does not adhere to Microsoft's Best-Practices of publishing
PowerShell modules, in the sense of that it does not use the *PowerShellGet*
module to do so and uses plain `nuget` CLI instead.
Execute `pwsh scripts/pack.ps1` to create a nuget package.
``$ pwsh -c "Invoke-Pester tools/*.Tests.ps1 -Show 'All'"`` Execute `pwsh scripts/publish` to publish the nuget package to
[PowerShellGallery](https://www.powershellgallery.com).