Improvement to ReadmeFile

rebelinux · Feb 19, 2024 · 9c81054 · 9c81054
1 parent dee03a1
commit 9c81054
Show file tree

Hide file tree

Showing 3 changed files with 128 additions and 89 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -16,7 +16,7 @@ body:
     attributes:
       label: Command-line input
       description: >-
-        Please provide the command line input you are using to run AsBuiltReport. Please ensure that you obscure any sensitive information.
+        Please provide the command line input you are using to run Diagrammer. Please ensure that you obscure any sensitive information.
     validations:
       required: true
   - type: textarea

diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 AsBuiltReport
+Copyright (c) 2024 Jonathan Colon
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -1,7 +1,6 @@
-<!-- ********** DO NOT EDIT THESE LINKS ********** -->
 <p align="center">
-    <a href="https://www.asbuiltreport.com/" alt="AsBuiltReport"></a>
-            <img src='https://github.com/AsBuiltReport.png' width="8%" height="8%" /></a>
+    <a href="https://github.com/rebelinux/Diagrammer.Core" alt="Diagrammer"></a>
+            <img src='https://avatars.githubusercontent.com/u/42958564' width="8%" height="8%" /></a>
 </p>
 <p align="center">
     <a href="https://www.powershellgallery.com/packages/Diagrammer.Core/" alt="PowerShell Gallery Version">
@@ -12,129 +11,169 @@
         <img src="https://img.shields.io/powershellgallery/p/Diagrammer.Core.svg" /></a>
 </p>
 <p align="center">
-    <a href="https://github.com/AsBuiltReport/Diagrammer.Core/graphs/commit-activity" alt="GitHub Last Commit">
-        <img src="https://img.shields.io/github/last-commit/AsBuiltReport/Diagrammer.Core/master.svg" /></a>
-    <a href="https://raw.githubusercontent.com/AsBuiltReport/Diagrammer.Core/master/LICENSE" alt="GitHub License">
-        <img src="https://img.shields.io/github/license/AsBuiltReport/Diagrammer.Core.svg" /></a>
-    <a href="https://github.com/AsBuiltReport/Diagrammer.Core/graphs/contributors" alt="GitHub Contributors">
-        <img src="https://img.shields.io/github/contributors/AsBuiltReport/Diagrammer.Core.svg"/></a>
+    <a href="https://github.com/rebelinux/Diagrammer.Core/graphs/commit-activity" alt="GitHub Last Commit">
+        <img src="https://img.shields.io/github/last-commit/rebelinux/Diagrammer.Core/master.svg" /></a>
+    <a href="https://raw.githubusercontent.com/rebelinux/Diagrammer.Core/master/LICENSE" alt="GitHub License">
+        <img src="https://img.shields.io/github/license/rebelinux/Diagrammer.Core.svg" /></a>
+    <a href="https://github.com/rebelinux/Diagrammer.Core/graphs/contributors" alt="GitHub Contributors">
+        <img src="https://img.shields.io/github/contributors/rebelinux/Diagrammer.Core.svg"/></a>
 </p>
 <p align="center">
-    <a href="https://twitter.com/AsBuiltReport" alt="Twitter">
-            <img src="https://img.shields.io/twitter/follow/AsBuiltReport.svg?style=social"/></a>
+    <a href="https://twitter.com/rebelinux" alt="Twitter">
+            <img src="https://img.shields.io/twitter/follow/rebelinux.svg?style=social"/></a>
 </p>
 
 <p align="center">
     <a href='https://ko-fi.com/B0B7DDGZ7' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://cdn.ko-fi.com/cdn/kofi1.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
 </p>
-<!-- ********** DO NOT EDIT THESE LINKS ********** -->
 
-# Diagrammer Core As Built Report
+# Diagrammer.Core
 
-<!-- ********** REMOVE THIS MESSAGE WHEN THE MODULE IS FUNCTIONAL ********** -->
-## :exclamation: THIS ASBUILTREPORT MODULE IS CURRENTLY IN DEVELOPMENT AND MIGHT NOT YET BE FUNCTIONAL ❗
-
-Diagrammer Core As Built Report is a PowerShell module which works in conjunction with [AsBuiltReport.Core](https://github.com/AsBuiltReport/AsBuiltReport.Core).
-
-[AsBuiltReport](https://github.com/AsBuiltReport/AsBuiltReport) is an open-sourced community project which utilises PowerShell to produce as-built documentation in multiple document formats for multiple vendors and technologies.
-
-Please refer to the AsBuiltReport [website](https://www.asbuiltreport.com) for more detailed information about this project.
+Diagrammer.Core is a PowerShell module which provides the core framework for generating as built diagrams for many common datacenter systems. The Diagrammer.Core module is required by each individual diagrammer module used to generate as built diagrams for a specific product and/or technology.
 
 # :beginner: Getting Started
-Below are the instructions on how to install, configure and generate a Diagrammer Core As Built report.
 
-## :floppy_disk: Supported Versions
-<!-- ********** Update supported Core versions ********** -->
-The Diagrammer Core As Built Report supports the following Core versions;
+The following simple list of instructions will get you started with the Diagrammer.Core module.
 
-### PowerShell
-This report is compatible with the following PowerShell versions;
+## :floppy_disk: Supported Versions
+### **PowerShell**
+This module is compatible with the following PowerShell versions;
 
-<!-- ********** Update supported PowerShell versions ********** -->
-| Windows PowerShell 5.1 |     PowerShell 7    |
-|:----------------------:|:--------------------:|
+| Windows PowerShell 5.1 |    PowerShell 7    |
+| :--------------------: | :----------------: |
 |   :white_check_mark:   | :white_check_mark: |
+
 ## :wrench: System Requirements
-<!-- ********** Update system requirements ********** -->
-PowerShell 5.1 or PowerShell 7, and the following PowerShell modules are required for generating a Diagrammer Core As Built Report.
 
-- [Diagrammer.Core Module](https://www.powershellgallery.com/packages/AsBuiltReport.Diagrammer.Core/)
+The following PowerShell module will be automatically installed by following the [module installation](https://github.com/rebelinux/Diagrammer.Core#package-module-installation) procedure.
+
+This PowerShell module may also be manually installed via the PowerShell Gallery or GitHub.
+
+| Module Name | Minimum Required Version |                         PS Gallery                         |                           GitHub                            |
+| ----------- | :----------------------: | :--------------------------------------------------------: | :---------------------------------------------------------: |
+| PScribo     |          0.10.0          | [Link](https://www.powershellgallery.com/packages/PScribo) | [Link](https://github.com/iainbrighton/PScribo/tree/master) |
+
+To find a list of available report modules, run the following PowerShell command;
 
-### :closed_lock_with_key: Required Privileges
-<!-- ********** Define required privileges ********** -->
-<!-- ********** Try to follow best practices to define least privileges ********** -->
+```powershell
+Find-Module -Name rebelinux.* -Repository PSGallery
+```
+
+The pre-requisites for each report type will be documented within its own `README.md` located in the relevant report repository.
 
 ## :package: Module Installation
 
 ### PowerShell
-<!-- ********** Add installation for any additional PowerShell module(s) ********** -->
+#### Online Installation
+
+For an online installation, install the `Diagrammer.Core` module using the [PowerShell Gallery](https://www.powershellgallery.com/packages?q=Diagrammer.Core);
+
 ```powershell
-install-module Diagrammer.Core
+# Install Diagrammer.Core module
+Install-Module -Name 'Diagrammer.Core' -Repository 'PSGallery' -Scope 'CurrentUser'
 ```
 
-### GitHub
-If you are unable to use the PowerShell Gallery, you can still install the module manually. Ensure you repeat the following steps for the [system requirements](https://github.com/AsBuiltReport/Diagrammer.Core#wrench-system-requirements) also.
+#### Offline Installation
 
-1. Download the code package / [latest release](https://github.com/AsBuiltReport/Diagrammer.Core/releases/latest) zip from GitHub
-2. Extract the zip file
-3. Copy the folder `Diagrammer.Core` to a path that is set in `$env:PSModulePath`.
-4. Open a PowerShell terminal window and unblock the downloaded files with
-    ```powershell
-    $path = (Get-Module -Name Diagrammer.Core -ListAvailable).ModuleBase; Unblock-File -Path $path\*.psd1; Unblock-File -Path $path\Src\Public\*.ps1; Unblock-File -Path $path\Src\Private\*.ps1
-    ```
-5. Close and reopen the PowerShell terminal window.
+For an offline installation, perform the following steps from a machine with internet connectivity;
 
-_Note: You are not limited to installing the module to those example paths, you can add a new entry to the environment variable PSModulePath if you want to use another path._
+Save the required `Diagrammer.Core` module to a specified folder.
 
-## :pencil2: Configuration
+```powershell
+# Save Diagrammer.Core module
+Save-Module -Name 'Diagrammer.Core' -Repository 'PSGallery' -Path '<Folder Path>'
+```
 
-The Diagrammer Core As Built Report utilises a JSON file to allow configuration of report information, options, detail and healthchecks.
+Copy the downloaded `Diagrammer.Core` module folder to a location that can be made accessible to the offline system.
+e.g. USB Flash Drive, Internal File Share etc.
 
-A Diagrammer Core report configuration file can be generated by executing the following command;
-```powershell
-New-AsBuiltReportConfig -Report Diagrammer.Core -FolderPath <User specified folder> -Filename <Optional>
+On the offline system, open a PowerShell console window and run the following command to determine the PowerShell module path.
+
+**Windows**
+
+```powershell title=""
+$env:PSModulePath -Split ';'
 ```
 
-Executing this command will copy the default Diagrammer Core report JSON configuration to a user specified folder.
+**macOS & Linux**
 
-All report settings can then be configured via the JSON file.
+```powershell title=""
+$env:PSModulePath -Split ':'
+```
 
-The following provides information of how to configure each schema within the report's JSON file.
+Copy the downloaded `Diagrammer.Core` module folder to a folder specified in the `$env:PSModulePath` output.
 
-<!-- ********** DO NOT CHANGE THE REPORT SCHEMA SETTINGS ********** -->
-### Report
-The **Report** schema provides configuration of the Diagrammer Core report information.
+### **GitHub**
+If you are unable to use the PowerShell Gallery, you can still install the `Diagrammer.Core` module manually. Ensure you repeat the following steps for the [system requirements](https://github.com/rebelinux/Diagrammer.Core#wrench-system-requirements) also.
 
-| Sub-Schema          | Setting      | Default                        | Description                                                  |
-|---------------------|--------------|--------------------------------|--------------------------------------------------------------|
-| Name                | User defined | Diagrammer Core As Built Report | The name of the As Built Report                              |
-| Version             | User defined | 1.0                            | The report version                                           |
-| Status              | User defined | Released                       | The report release status                                    |
-| ShowCoverPageImage  | true / false | true                           | Toggle to enable/disable the display of the cover page image |
-| ShowTableOfContents | true / false | true                           | Toggle to enable/disable table of contents                   |
-| ShowHeaderFooter    | true / false | true                           | Toggle to enable/disable document headers & footers          |
-| ShowTableCaptions   | true / false | true                           | Toggle to enable/disable table captions/numbering            |
+1. Download the [latest release](https://github.com/rebelinux/Diagrammer.Core/releases/latest) zip from GitHub
+2. Extract the zip file
+3. Copy the folder `Diagrammer.Core` to a path that is set in `$env:PSModulePath`.
+4. For Windows users only, open a PowerShell terminal window and unblock the downloaded files with
+    ```powershell
+    $path = (Get-Module -Name Diagrammer.Core -ListAvailable).ModuleBase; Unblock-File -Path $path\*.psd1; Unblock-File -Path $path\Src\Public\*.ps1
+    ```
+5. Close and reopen the PowerShell terminal window.
 
-### Options
-The **Options** schema allows certain options within the report to be toggled on or off.
+_Note: You are not limited to installing the module to those example paths, you can add a new entry to the environment variable PSModulePath if you want to use another path._
 
-<!-- ********** Add/Remove the number of InfoLevels as required ********** -->
-### InfoLevel
-The **InfoLevel** schema allows configuration of each section of the report at a granular level. The following sections can be set.
+## :pencil2: Commands
 
-There are 6 levels (0-5) of detail granularity for each section as follows;
+### **New-rebelinux**
 
-| Setting | InfoLevel         | Description                                                                                                                                |
-|:-------:|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
-|    0    | Disabled          | Does not collect or display any information                                                                                                |
-|    1    | Enabled / Summary | Provides summarised information for a collection of objects                                                                                |
-|    2    | Adv Summary       | Provides condensed, detailed information for a collection of objects                                                                       |
-|    3    | Detailed          | Provides detailed information for individual objects                                                                                       |
-|    4    | Adv Detailed      | Provides detailed information for individual objects, as well as information for associated objects                                        |
-|    5    | Comprehensive     | Provides comprehensive information for individual objects, such as advanced configuration settings                                         |
+The `New-rebelinux` cmdlet is used to generate as built reports. The type of as built report to generate is specified by using the `Report` parameter. The report parameter relies on additional report modules being installed alongside the `Diagrammer.Core` module. The `Target` parameter specifies one or more systems on which to connect and run the report. User credentials to the system are specified using the `Credential`, or the `Username` and `Password` parameters. One or more document formats, such as `HTML`, `Word` or `Text` can be specified using the `Format` parameter. Additional parameters are outlined below.
 
-### Healthcheck
-The **Healthcheck** schema is used to toggle health checks on or off.
+```powershell
+.PARAMETER Report
+    Specifies the type of report that will be generated.
+.PARAMETER Target
+    Specifies the IP/FQDN of the system to connect.
+    Multiple targets may be specified, separated by a comma.
+.PARAMETER Credential
+    Specifies the stored credential of the target system.
+.PARAMETER Username
+    Specifies the username for the target system.
+.PARAMETER Password
+    Specifies the password for the target system.
+.PARAMETER Token
+    Specifies an API token to authenticate to the target system.
+.PARAMETER MFA
+    Use multifactor authentication to authenticate to the target system.
+.PARAMETER Format
+    Specifies the output format of the report.
+    The supported output formats are WORD, HTML & TEXT.
+    Multiple output formats may be specified, separated by a comma.
+.PARAMETER Orientation
+    Sets the page orientation of the report to Portrait or Landscape.
+    By default, page orientation will be set to Portrait.
+.PARAMETER StyleFilePath
+    Specifies the file path to a custom style .ps1 script for the report to use.
+.PARAMETER OutputFolderPath
+    Specifies the folder path to save the report.
+.PARAMETER Filename
+    Specifies a filename for the report.
+.PARAMETER Timestamp
+    Specifies whether to append a timestamp string to the report filename.
+    By default, the timestamp string is not added to the report filename.
+.PARAMETER EnableHealthCheck
+    Performs a health check of the target environment and highlights known issues within the report.
+    Not all reports may provide this functionality.
+.PARAMETER SendEmail
+    Sends report to specified recipients as email attachments.
+.PARAMETER AsBuiltConfigFilePath
+    Enter the full path to the As Built Report configuration JSON file.
+    If this parameter is not specified, the user will be prompted for this configuration information on first
+    run, with the option to save the configuration to a file.
+.PARAMETER ReportConfigFilePath
+    Enter the full path to a report JSON configuration file.
+    If this parameter is not specified, a default report configuration JSON is copied to the specified user folder.
+    If this parameter is specified and the path to a JSON file is invalid, the script will terminate
+```
+
+For a full list of common parameters and examples you can view the `New-rebelinux` cmdlet help with the following command;
+
+```powershell
+Get-Help New-rebelinux -Full
+```
 
-## :computer: Examples
-<!-- ********** Add some examples. Use other AsBuiltReport modules as a guide. ********** -->
+## :x: Known Issues