From 6960f84bb8bdf360eba7cfce445e5da3c050c468 Mon Sep 17 00:00:00 2001 From: HumanAgainstMachine Date: Sun, 20 Oct 2024 10:55:22 +0200 Subject: [PATCH] Update documentation content and look with material for MkDocs --- docs/LocalRepo.md | 55 +++++++++++++++++++++++++++ docs/index.md | 94 +++++++++++------------------------------------ mkdocs.yml | 35 +++++++++++++++--- 3 files changed, 107 insertions(+), 77 deletions(-) create mode 100644 docs/LocalRepo.md diff --git a/docs/LocalRepo.md b/docs/LocalRepo.md new file mode 100644 index 0000000..0cc5593 --- /dev/null +++ b/docs/LocalRepo.md @@ -0,0 +1,55 @@ +# The Local Repo + +**LocalModules** additionally supports setting up a local repository for testing PS module publishing. + +## Intro + +When you are ready to publish your module officially, for example to powershellgallery.com, you want to test the publishing process and you can do this with a local *file share repository* (1). +{ .annotate } + +1. :material-cursor-default-click: 2. [Kevin Marquette's article about file share repositories](https://powershellexplained.com/2017-05-30-Powershell-your-first-PSScript-repository/). + +LocalModules Powershell module additionally enables you to set up a local repository on your system to the folder `$HOME\LocalRepo`. + +### Local Repo cmdlets overview + +`#!powershell Set-LRepo` +: Set up a local *file share* repository named LocalRepo. + +`#!powershell Remove-LRepo` +: Remove the LocalRepo repository and all modules that are contained. + + +### Examples + +Setting up the repo: +```powershell +PS:> Set-LRepo +``` +Checking out LocalRepo: + +```powershell +PS:> Get-PSRepository + +Name InstallationPolicy SourceLocation +---- ------------------ -------------- +PSGallery Untrusted https://www.powershellgallery.com/api/v2 +LocalRepo Trusted C:\Users\\LocalRepo +``` + +Publishing to LocalRepo: + +```powershell +PS:> Publish-Module -Name -Repository LocalRepo +``` + +Installing a module from LocalRepo: + +```powershell +PS:> Install-Module -Name -Repository LocalRepo +``` + +Removing the repo +```powershell +PS:> Remove-LRepo +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 5936dab..e74dcec 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,103 +1,53 @@ # LocalModules +**LocalModules** allows you to easily install and uninstall PowerShell (PS) modules that are still under development and not yet ready for publishing. This streamlines the development and testing process. + ## Intro -In this context, a local module is a module under development with a file layout like this: +In this context, a local module is a Powershell module under development with a file layout like this: - ModName/ - ModName.psm1 # The code file. - ... # Other files, e.g. manifest file. + MyModuleNameFolder/ + MyModuleName.psm1 # The code file. + MyModuleName.psd1 # The manifest. + ... # Other files, e.g. manifest file. While developing a PowerShell module on your computer, you will often need to install it on your system to test it. Installing from a repository requires you to go through the long process of first publishing the module. There is a shortcut to install a local module bypassing repositories, this involves copying the module folder and files to a directory on your Windows computer. -As Microsoft says1: +!!! quote "As Microsoft says:" + To install and run your module, save the module to one of the appropriate PowerShell paths [...]. The paths where you can install your module are located in the `$env:PSModulePath` global variable. ->To install and run your module, save the module to one of the appropriate PowerShell paths [...]. The paths where you can install your module are located in the `$env:PSModulePath` global variable. + :material-cursor-default-click: [How to Write a PowerShell Script Module](https://learn.microsoft.com/en-us/powershell/scripting/developer/module/how-to-write-a-powershell-script-module?view=powershell-7.4). -So the directory must be one listed in the `$env:PSModulePath` global variable, a good one for developing purposes is the user-specific directory `$HOME\Documents\PowerShell\Modules`. -## How it works -LocalModules speeds up this installation process, handles removing the previously installed local module before copying the new one and avoids mixing up local and repo modules. +So the directory must be one listed in the `$env:PSModulePath` global variable, a good one for developing purposes is the user-specific directory `$HOME\Documents\PowerShell\Modules`. -LocalModules installs the module in your user-specific Powershell path and allows you to `install`, `uninstall` and, `list` modules that have not been yet published in a repository, facilitating a quicker development and testing cycle. +## How it works +**LocalModules** speeds up this installation process, handles removing the previously installed local module before copying the new one and avoids mixing up local and repo modules. +**LocalModules** installs the under-development module in your user-specific Powershell path and allows you to `install`, `uninstall` and, `list` modules that have not been yet published in a repository, facilitating a quicker development and testing cycle. ## Installation -Install LocalModules from [Powershell Gallery](https://www.powershellgallery.com/packages/LocalModules). +Install **LocalModules** from [Powershell Gallery](https://www.powershellgallery.com/packages/LocalModules). ```powershell Install-Module -Name LocalModules ``` -## Usage +## Cmdlets overview -Install specifying an absolute or relative path to the local module folder. +`#!powershell Install-LModule -Path ` +: Install the local module specified by `-Path` parameter; it can be an absolute or relative path. -```powershell -Install-LocalModule -Path -``` -List all installed local modules. - -```powershell -Get-LocalInstalledModule -``` -Uninstall specifying the local module name to remove. -```powershell -Uninstall-LocalModule -Name -``` - -## Local Repo extra feature - -When you are ready to publish your module officially, for example, to powershellgallery.com, you want to test the publishing process and you can do this with a local *file share repository*2. - -LocalModules Powershell module additionally enables you to set up a local repository on your system to the folder `$HOME\LocalRepo`. - -### Usage - -Set up a local *file share* repository named LocalRepo. - -```powershell -Set-LocalRepo -``` - -Remove the LocalRepo repository and all modules that are contained. - -```powershell -Remove-LocalRepo -``` - -### Examples - -Check out LocalRepo: - -```powershell -PS:> Get-PSRepository - -Name InstallationPolicy SourceLocation ----- ------------------ -------------- -PSGallery Untrusted https://www.powershellgallery.com/api/v2 -LocalRepo Trusted C:\Users\\LocalRepo -``` - -For publish to and install from LocalRepo specify it in commands: - -```powershell -PS:> Publish-Module -Name -Repository LocalRepo -``` - -```powershell -PS:> Install-Module -Name -Repository LocalRepo -``` +`#!powershell Get-LInstalledModule` +: List all local modules installed with `#!powershell Install-LModule`. ---- -## Endnotes -1. [How to Write a PowerShell Script Module](https://learn.microsoft.com/en-us/powershell/scripting/developer/module/how-to-write-a-powershell-script-module?view=powershell-7.4). -2. [Kevin Marquette's article about file share repositories](https://powershellexplained.com/2017-05-30-Powershell-your-first-PSScript-repository/). +`#!powershell Uninstall-LModule -Name ` +: Uninstall the local module specified by `-Name` parameter and previously installed with `#!powershell Install-LModule` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 1d8b64f..21fa4bd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,31 @@ -site_name: LocalModules Docs +site_name: LocalModules +site_url: https://humanagainstmachine.github.io/LocalModules/ +repo_url: https://github.com/HumanAgainstMachine/LocalModules +nav: +- LocalModules: index.md +- Local Repo: LocalRepo.md theme: - name: readthedocs - highlightjs: true - hljs_languages: - - powershell \ No newline at end of file + name: material + icon: + logo: fontawesome/solid/computer + annotation: material/plus-circle + language: en + features: + - navigation.tabs + # - navigation.tabs.sticky + - toc.integrate + - navigation.top + - content.code.copy + - navigation.footer + +markdown_extensions: + - pymdownx.highlight + - pymdownx.inlinehilite + - pymdownx.superfences + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - def_list + - admonition + - attr_list + - md_in_html