From c134776f47cef5b1ac392a6c3422d079cff9c51f Mon Sep 17 00:00:00 2001 From: "Rodweil, Theodor" Date: Tue, 8 Aug 2023 23:31:44 +0200 Subject: [PATCH] chore: update README --- README.md | 36 ++++++++++++++++++++++++------------ 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 002b979..c246505 100755 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ This program is a standalone publisher component for the Sphinx extension. 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. 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 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. +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 @@ -29,11 +30,11 @@ interchange with the original manifest producer system ## Usage -You will be able to install the module via [nuget](https://www.nuget.org). This -however is not yet possible. +You may install this PowerShell module via +[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, @@ -47,8 +48,7 @@ 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') +PS> Import-Module "src/PSConfluencePublisher.psd1" ``` 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) 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 -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).