platyPS help migration and doc site (#378)

rmbolger · Sep 1, 2021 · c7ca310 · c7ca310
1 parent 5969855
commit c7ca310
Show file tree

Hide file tree

Showing 140 changed files with 15,123 additions and 2,234 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -10,9 +10,34 @@ I'm the first to admit that I don't test nearly as much as I should. If you run
 
 ### DNS Plugins
 
-If you want your provider supported but can't write the plugin yourself, submit an issue with the request and I'm happy to give it a try. But the hardest part about writing new DNS plugins is usually getting an account with the provider to test with. Providers with free trials or sandbox/test environments are great. Otherwise, I just need temporary access to an existing account **or** a [donation](https://paypal.me/rmbolger) to cover the cost of setting up a new account with the provider.
+If you want your provider supported but can't write the plugin yourself, submit an issue with the request and I'm happy to give it a try. But the hardest part about writing new DNS plugins is usually getting an account with the provider to test with. Providers with free trials or sandbox/test environments are great. Otherwise, I just need temporary access to an existing account **or** a [donation](https://github.com/sponsors/rmbolger?frequency=one-time) to cover the cost of setting up a new account with the provider.
 
-Pull requests for plugins you've written are also encouraged. I still tend to try and test them myself before merging them which goes back to the hassles of getting an account with the provider to test with. But that's mostly so that I'm confident I can support the plugin long term without needing to pull you back in to support it if someone submits and issue with it.
+Pull requests for plugins you've written are also encouraged. I still try and test them myself before merging them which goes back to the hassles of getting an account with the provider to test with. But that's mostly so that I'm confident I can support the plugin long term without needing to pull you back in to support it if someone submits and issue with it.
+
+## Native Module Help
+
+The native module help is now generated by [platyPS](https://github.com/PowerShell/platyPS) from the Markdown files in [docs/Functions](https://github.com/rmbolger/Posh-ACME/tree/main/docs/Functions). So if you want to contribute fixes or improvements, submit a pull request with changes to those files.
+
+If you are editing the files locally, you can optionally install and generate the updated MAML XML help with platyPS as follows.
+
+- Make sure the latest platyPS release is installed
+- From the repository root folder run `.\gen-maml.ps1`
+- Force re-import the module from the repository folder or run `.\instdev.ps1` to install the dev version to the current user's profile
+- Run `Get-Help <function name>` to see your changes
+
+Including the updated MAML with your pull request is appreciated but not required.
+
+## Documentation Website
+
+In addition to the native module help, we have a documentation website at [https://poshac.me/docs/](https://poshac.me/docs) that is generated by [MkDocs](https://www.mkdocs.org/) from the Markdown files in [docs/](https://github.com/rmbolger/Posh-ACME/tree/main/docs/). Fixes, improvements, new guides, and new links to external articles are all welcome additions. So feel free to submit a pull request for those as well.
+
+Testing the doc site changes locally is a bit more involved because MkDocs is written in Python. You'll need a recent Python 3.x environment plus some additional packages. Follow the [MkDocs install guide](https://www.mkdocs.org/user-guide/installation/) and add the following additional packages with `pip install <package>`.
+
+- mkdocs-material
+- mkdocs-awesome-pages-plugin
+- mike
+
+Checkout the main branch of the repository and run `mkdocs serve` to self-host a copy of the current documentation site. The output of the command should tell you the URL to use.
 
 ## Unit Tests
 
@@ -30,10 +55,6 @@ pwsh.exe -C "Invoke-Pester"
 
 Keep in mind, the tests should be able to pass on both Windows PowerShell 5.1 and PowerShell 6+ on any OS.
 
-## The Wiki
-
-Is there some documentation you wish you had when you were first playing with the module? Did I make a spelling mistake? Is my grammar poor? Did you write a blog post or article somewhere about using the module. Submit an issue and tell me about any of these things.
-
 ## Features and Functionality
 
 I know there are loads of use cases I haven't considered. If you have an idea for a new feature or functionality change, submit an issue first so we can discuss it. I'd hate for you to waste time implementing a feature that I may never pull into the project.

diff --git a/Posh-ACME/Plugins/README.md b/Posh-ACME/Plugins/README.md
diff --git a/Posh-ACME/Public/Complete-PAOrder.ps1 b/Posh-ACME/Public/Complete-PAOrder.ps1
@@ -81,36 +81,4 @@ function Complete-PAOrder {
         # output cert details
         return $cert
     }
-
-
-    <#
-    .SYNOPSIS
-        Exports cert files for a completed order and adds suggested renewal window to the order.
-
-    .DESCRIPTION
-        Once an ACME order is finalized, the signed certificate and chain can be downloaded and combined with the local private key to generate the supported PEM and PFX files on disk. This function will also calculate the renewal window based on the signed certificate's expiration date and update the order object with that info. If the Install flag is set, this function will attempt to import the certificate into the Windows certificate store.
-
-    .PARAMETER Order
-        The ACME order to complete. The order object must be associated with the currently active ACME account.
-
-    .EXAMPLE
-        Complete-PAOrder
-
-        Complete the current order.
-
-    .EXAMPLE
-        Get-PAOrder example.com | Complete-PAOrder
-
-        Complete the specified order.
-
-    .LINK
-        Project: https://github.com/rmbolger/Posh-ACME
-
-    .LINK
-        Get-PAOrder
-
-    .LINK
-        New-PAOrder
-
-    #>
 }
diff --git a/Posh-ACME/Public/Export-PAAccountKey.ps1 b/Posh-ACME/Public/Export-PAAccountKey.ps1
@@ -55,48 +55,4 @@ function Export-PAAccountKey {
         Export-Pem $keypair $OutputFile
 
     }
-
-
-    <#
-    .SYNOPSIS
-        Export an ACME account private key.
-
-    .DESCRIPTION
-        The account key is saved as an unencrypted Base64 encoded PEM file.
-
-    .PARAMETER ID
-        The ACME account ID value.
-
-    .PARAMETER OutputFile
-        The path to the file to write the key data to.
-
-    .PARAMETER Force
-        If specified and the output file already exists, it will be overwritten. Without the switch, a confirmation prompt will be presented.
-
-    .EXAMPLE
-        Export-PAAccountKey -OutputFile .\mykey.pem
-
-        Exports the current ACME account's key to the specified file.
-
-    .EXAMPLE
-        Export-PAAccountKey 12345 -OutputFile .\mykey.pem -Force
-
-        Exports the specified ACME account's key to the specified file and overwrites it if necessary.
-
-    .EXAMPLE
-        $fldr = Join-Path ([Environment]::GetFolderPath('Desktop')) 'AcmeAccountKeys'
-        PS C:\>New-Item -ItemType Directory -Force -Path $fldr | Out-Null
-        PS C:\>Get-PAAccount -List | %{
-        PS C:\>    Export-PAAccountKey $_.ID -OutputFile "$fldr\$($_.ID).key" -Force
-        PS C:\>}
-
-        Backup all account keys for this ACME server to a folder on the desktop.
-
-    .LINK
-        Project: https://github.com/rmbolger/Posh-ACME
-
-    .LINK
-        Get-PAAccount
-
-    #>
 }
diff --git a/Posh-ACME/Public/Get-KeyAuthorization.ps1 b/Posh-ACME/Public/Get-KeyAuthorization.ps1
@@ -75,44 +75,4 @@ function Get-KeyAuthorization {
             return $keyAuth
         }
     }
-
-
-
-
-    <#
-    .SYNOPSIS
-        Calculate a key authorization string for a challenge token.
-
-    .DESCRIPTION
-        A key authorization is a string that expresses a domain holder's authorization for a specified key to satisfy a specified challenge, by concatenating the token for the challenge with a key fingerprint.
-
-    .PARAMETER Token
-        The token string for an ACME challenge.
-
-    .PARAMETER Account
-        The ACME account associated with the challenge.
-
-    .PARAMETER ForDNS
-        Enable this switch if you're using the key authorization value for the 'dns-01' challenge type. It will do a few additional manipulation steps on the value that are required for a DNS TXT record.
-
-    .EXAMPLE
-        Get-KeyAuthorization 'XxXxXxXxXxXx'
-
-        Get the key authorization for the specified token using the current account.
-
-    .EXAMPLE
-        (Get-PAOrder | Get-PAAuthorization).DNS01Token | Get-KeyAuthorization
-
-        Get all key authorizations for the DNS challenges in the current order using the current account.
-
-    .LINK
-        Project: https://github.com/rmbolger/Posh-ACME
-
-    .LINK
-        Get-PAAuthorization
-
-    .LINK
-        Submit-ChallengeValidation
-
-    #>
 }
diff --git a/Posh-ACME/Public/Get-PAAccount.ps1 b/Posh-ACME/Public/Get-PAAccount.ps1
@@ -131,77 +131,4 @@ function Get-PAAccount {
             }
         }
     }
-
-
-
-
-
-    <#
-    .SYNOPSIS
-        Get ACME account details.
-
-    .DESCRIPTION
-        Returns details such as Email, key length, and status for one or more ACME accounts previously created.
-
-    .PARAMETER ID
-        The account id value as returned by the ACME server. 'Name' is also an alias for this parameter.
-
-    .PARAMETER List
-        If specified, the details for all accounts will be returned.
-
-    .PARAMETER Status
-        A Status string to filter the list of accounts with.
-
-    .PARAMETER Contact
-        One or more email addresses to filter the list of accounts with. Returned accounts must match exactly (not including the order).
-
-    .PARAMETER KeyLength
-        The type and size of private key to filter the list of accounts with. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'.
-
-    .PARAMETER Refresh
-        If specified, any account details returned will be freshly queried from the ACME server (excluding deactivated accounts). Otherwise, cached details will be returned.
-
-    .PARAMETER ExtraParams
-        This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports.
-
-    .EXAMPLE
-        Get-PAAccount
-
-        Get cached ACME account details for the currently selected account.
-
-    .EXAMPLE
-        Get-PAAccount -ID 1234567
-
-        Get cached ACME account details for the specified account ID.
-
-    .EXAMPLE
-        Get-PAAccount -List
-
-        Get all cached ACME account details.
-
-    .EXAMPLE
-        Get-PAAccount -Refresh
-
-        Get fresh ACME account details for the currently selected account.
-
-    .EXAMPLE
-        Get-PAAccount -List -Refresh
-
-        Get fresh ACME account details for all accounts.
-
-    .EXAMPLE
-        Get-PAAccount -List -Contact [email protected]
-
-        Get cached ACME account details for all accounts that have [email protected] as the only contact.
-
-    .LINK
-        Project: https://github.com/rmbolger/Posh-ACME
-
-    .LINK
-        Set-PAAccount
-
-    .LINK
-        New-PAAccount
-
-    #>
 }
diff --git a/Posh-ACME/Public/Get-PAAuthorization.ps1 b/Posh-ACME/Public/Get-PAAuthorization.ps1
@@ -53,47 +53,4 @@ function Get-PAAuthorization {
             ConvertTo-PAAuthorization $response.Content $AuthUrl
         }
     }
-
-
-
-
-
-    <#
-    .SYNOPSIS
-        Get the authorizations associated with a particular order or set of authorization URLs.
-
-    .DESCRIPTION
-        Returns details such as fqdn, status, expiration, and challenges for one or more ACME authorizations.
-
-    .PARAMETER AuthURLs
-        One or more authorization URLs. These will be picked up automatically if you send PoshACME.PAOrder objects through the pipeline.
-
-    .PARAMETER Account
-        An existing ACME account object such as the output from Get-PAAccount. If no account is specified, the current account will be used.
-
-    .EXAMPLE
-        Get-PAAuthorization https://acme.example.com/authz/1234567
-
-        Get the authorization for the specified URL.
-
-    .EXAMPLE
-        Get-PAOrder | Get-PAAuthorization
-
-        Get the authorization(s) for the current order on the current account.
-
-    .EXAMPLE
-        Get-PAOrder -List | Get-PAAuthorization
-
-        Get the authorization(s) for all orders on the current account.
-
-    .LINK
-        Project: https://github.com/rmbolger/Posh-ACME
-
-    .LINK
-        Get-PAOrder
-
-    .LINK
-        New-PAOrder
-
-    #>
 }
diff --git a/Posh-ACME/Public/Get-PACertificate.ps1 b/Posh-ACME/Public/Get-PACertificate.ps1
@@ -94,47 +94,4 @@ function Get-PACertificate {
         }
 
     }
-
-
-
-
-
-    <#
-    .SYNOPSIS
-        Get ACME certificate details.
-
-    .DESCRIPTION
-        Returns details such as Thumbprint, Subject, Validity, SANs, and file locations for one or more ACME certificates previously created.
-
-    .PARAMETER MainDomain
-        The primary domain associated with the certificate. This is the domain that goes in the certificate's subject.
-
-    .PARAMETER Name
-        The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain.
-
-    .PARAMETER List
-        If specified, the details for all completed certificates will be returned for the current account.
-
-    .EXAMPLE
-        Get-PACertificate
-
-        Get cached ACME order details for the currently selected order.
-
-    .EXAMPLE
-        Get-PACertificate site.example.com
-
-        Get cached ACME order details for the specified domain.
-
-    .EXAMPLE
-        Get-PACertificate -List
-
-        Get all cached ACME order details.
-
-    .LINK
-        Project: https://github.com/rmbolger/Posh-ACME
-
-    .LINK
-        New-PACertificate
-
-    #>
 }