Skip to content

Add GitHub Actions workflow for documentation generation #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 9, 2025
Merged

Add GitHub Actions workflow for documentation generation #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
53488ed
Enhance README with improved documentation and visual elements
Aug 9, 2025
9336a04
Add GitHub Actions workflow for documentation generation
Aug 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 163 additions & 0 deletions .github/workflows/docs-workflow.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
name: PowerShell Documentation

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
schedule:
- cron: '0 0 * * 5' # Weekly run on Friday at midnight

jobs:
validate:
name: Validate PowerShell Scripts
runs-on: windows-latest

steps:
- uses: actions/checkout@v3

- name: Install PSScriptAnalyzer
shell: pwsh
run: |
Set-PSRepository PSGallery -InstallationPolicy Trusted
Install-Module -Name PSScriptAnalyzer -Force

- name: Lint with PSScriptAnalyzer
shell: pwsh
run: |
$results = Invoke-ScriptAnalyzer -Path ./commands -Recurse -Settings PSGallery
$results | Format-Table -AutoSize
if ($results) {
Write-Warning "PSScriptAnalyzer found issues. Please review them."
$results | Format-Table -AutoSize
}

- name: Check PowerShell syntax
shell: pwsh
run: |
$files = Get-ChildItem -Path ./commands -Include *.ps1,*.psm1 -Recurse
foreach ($file in $files) {
$syntaxErrors = $null
$null = [System.Management.Automation.PSParser]::Tokenize((Get-Content -Path $file.FullName -Raw), [ref]$syntaxErrors)
if ($syntaxErrors.Count -gt 0) {
Write-Error "Syntax errors in $($file.FullName)"
$syntaxErrors | Format-Table -AutoSize
exit 1
}
}

build-docs:
name: Build Documentation
runs-on: ubuntu-latest
needs: validate

steps:
- uses: actions/checkout@v3

- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.10'

- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install mkdocs mkdocs-material pymdown-extensions

- name: Generate command documentation
shell: bash
run: |
mkdir -p docs/commands
for file in commands/*.ps1; do
filename=$(basename "$file" .ps1)
echo "# $filename Commands" > "docs/commands/${filename}.md"
echo '```powershell' >> "docs/commands/${filename}.md"
cat "$file" >> "docs/commands/${filename}.md"
echo '```' >> "docs/commands/${filename}.md"
done

- name: Build documentation
run: |
mkdocs build

- name: Deploy to GitHub Pages
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./site

update-readme:
name: Update README with Command Count
runs-on: ubuntu-latest
needs: validate
if: github.event_name == 'push' && github.ref == 'refs/heads/main'

steps:
- uses: actions/checkout@v3

- name: Count commands
id: count
shell: bash
run: |
TOTAL_COUNT=$(grep -r "function " ./commands | wc -l)
echo "TOTAL_COUNT=$TOTAL_COUNT" >> $GITHUB_ENV

AD_COUNT=$(grep -r "function " ./commands/active-directory.ps1 2>/dev/null | wc -l || echo "0")
echo "AD_COUNT=$AD_COUNT" >> $GITHUB_ENV

AZURE_COUNT=$(grep -r "function " ./commands/azure-m365.ps1 2>/dev/null | wc -l || echo "0")
echo "AZURE_COUNT=$AZURE_COUNT" >> $GITHUB_ENV

SECURITY_COUNT=$(grep -r "function " ./commands/security.ps1 2>/dev/null | wc -l || echo "0")
echo "SECURITY_COUNT=$SECURITY_COUNT" >> $GITHUB_ENV

- name: Update README
uses: actions/github-script@v6
with:
script: |
const fs = require('fs');
const readme = fs.readFileSync('README.md', 'utf8');

// Update command count in the description
let updatedReadme = readme.replace(
/📘 Curated PowerShell command library for IT professionals - \d+\+ ready-to-use commands/,
`📘 Curated PowerShell command library for IT professionals - ${process.env.TOTAL_COUNT}+ ready-to-use commands`
);

// Add command count by category if not present
if (!updatedReadme.includes('## Command Count')) {
updatedReadme += `\n\n## Command Count\n\n`;
updatedReadme += `- **Total Commands**: ${process.env.TOTAL_COUNT}\n`;
updatedReadme += `- **Active Directory**: ${process.env.AD_COUNT}\n`;
updatedReadme += `- **Azure & Microsoft 365**: ${process.env.AZURE_COUNT}\n`;
updatedReadme += `- **Security**: ${process.env.SECURITY_COUNT}\n`;
} else {
// Update existing command count section
updatedReadme = updatedReadme.replace(
/- \*\*Total Commands\*\*: \d+/,
`- **Total Commands**: ${process.env.TOTAL_COUNT}`
);
updatedReadme = updatedReadme.replace(
/- \*\*Active Directory\*\*: \d+/,
`- **Active Directory**: ${process.env.AD_COUNT}`
);
updatedReadme = updatedReadme.replace(
/- \*\*Azure & Microsoft 365\*\*: \d+/,
`- **Azure & Microsoft 365**: ${process.env.AZURE_COUNT}`
);
updatedReadme = updatedReadme.replace(
/- \*\*Security\*\*: \d+/,
`- **Security**: ${process.env.SECURITY_COUNT}`
);
}

fs.writeFileSync('README.md', updatedReadme);

- name: Commit and push if changed
run: |
git config --global user.name 'GitHub Actions'
git config --global user.email 'actions@github.com'
git add README.md
git diff --quiet && git diff --staged --quiet || git commit -m "Update command count in README [skip ci]"
git push
199 changes: 181 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,187 @@
# PowerShell Command Reference
# PowerShell Command Reference Library

This repository serves as a curated reference of PowerShell commands categorized by use case. It is designed for quick lookup and practical usage, especially for IT administrators and engineers.
![PowerShell](https://img.shields.io/badge/PowerShell-5.1%2B-blue)
![Commands](https://img.shields.io/badge/Commands-100%2B-green)
![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)

## Categories
- Active Directory
- Azure and Microsoft 365
- File System and Disk Management
- Networking and Firewall
- Scheduled Tasks and Automation
- Security and Permissions
> 📘 Curated PowerShell command library for IT professionals - 100+ ready-to-use commands for AD, Azure, security, and automation tasks

## Usage
Each `.ps1` file includes a set of command snippets grouped by category. You can copy/paste them into your PowerShell terminal or integrate them into scripts as needed.
## 🚀 Overview

## Contributing
Pull requests are welcome. Please group related commands under the appropriate `.ps1` file or request a new category if needed.
This repository provides a comprehensive collection of PowerShell commands and scripts organized by category for IT professionals, system administrators, and cloud engineers. Each command includes detailed explanations, usage examples, and best practices.

## License
MIT License. See `LICENSE` for details.
## 📋 Categories

## Author
Jaquan Watson
[Portfolio](https://jaquanwatson.github.io) | [GitHub](https://github.com/jaquanwatson)
<table>
<tr>
<td><b>🔹 Active Directory</b></td>
<td>User management, group policies, domain operations, security groups</td>
</tr>
<tr>
<td><b>☁️ Azure & Microsoft 365</b></td>
<td>Resource management, tenant administration, Exchange Online, SharePoint</td>
</tr>
<tr>
<td><b>💾 File System & Storage</b></td>
<td>File operations, disk management, permissions, backup/restore</td>
</tr>
<tr>
<td><b>🌐 Networking</b></td>
<td>DNS, DHCP, firewall configuration, connectivity testing</td>
</tr>
<tr>
<td><b>🔒 Security & Compliance</b></td>
<td>Auditing, permissions, encryption, compliance reporting</td>
</tr>
<tr>
<td><b>⚙️ Automation</b></td>
<td>Scheduled tasks, workflows, event triggers, reporting</td>
</tr>
</table>

## 📖 How to Use This Repository

### Command Files Structure

Each category has its own `.ps1` file containing related commands:

```
commands/
├── active-directory.ps1
├── azure-m365.ps1
├── file-system.ps1
├── networking.ps1
├── security.ps1
└── automation.ps1
```

### Documentation Structure

Comprehensive documentation is available in the `docs/` folder:

```
docs/
├── active-directory.md
├── azure.md
├── file-system.md
├── networking.md
├── security.md
└── automation.md
```

### Usage Examples

Each command includes:
- Purpose and description
- Required parameters
- Example usage
- Expected output
- Common use cases

Example from `active-directory.ps1`:

```powershell
# Get all disabled user accounts in Active Directory
# Usage: Lists all disabled user accounts with their last logon time
function Get-DisabledADUsers {
Get-ADUser -Filter {Enabled -eq $false} -Properties LastLogonDate, DisplayName |
Select-Object DisplayName, SamAccountName, LastLogonDate |
Sort-Object LastLogonDate
}

# Example output:
# DisplayName SamAccountName LastLogonDate
# ----------- ------------- -------------
# John Smith jsmith 2023-05-15 10:30:45
# Jane Doe jdoe 2023-06-22 14:15:30
```

## 🔍 Quick Reference

### Most Popular Commands

<details>
<summary><b>Active Directory Commands</b></summary>

```powershell
# Get all locked out accounts
Search-ADAccount -LockedOut | Select-Object Name, SamAccountName

# Reset user password
Set-ADAccountPassword -Identity "username" -Reset -NewPassword (ConvertTo-SecureString -AsPlainText "NewPassword" -Force)

# Get inactive users (90+ days)
$date = (Get-Date).AddDays(-90)
Get-ADUser -Filter {LastLogonTimeStamp -lt $date -and Enabled -eq $true} -Properties LastLogonTimeStamp |
Select-Object Name, @{Name="LastLogon"; Expression={[DateTime]::FromFileTime($_.lastLogonTimestamp)}}
```
</details>

<details>
<summary><b>Azure & Microsoft 365 Commands</b></summary>

```powershell
# Connect to Microsoft 365
Connect-MsolService

# Get all licensed users
Get-MsolUser -All | Where-Object {$_.isLicensed -eq $true} | Select-Object DisplayName, UserPrincipalName, Licenses

# Get Azure AD sign-in logs
Get-AzureADAuditSignInLogs -Top 10 | Select-Object UserPrincipalName, AppDisplayName, Status, CreatedDateTime
```
</details>

<details>
<summary><b>Security Commands</b></summary>

```powershell
# Get failed login attempts
Get-EventLog -LogName Security -InstanceId 4625 -Newest 10

# Check file permissions
Get-Acl -Path "C:\path\to\file.txt" | Format-List

# Export security audit
Get-WinEvent -FilterHashtable @{LogName='Security'; ID=4624,4625,4634} -MaxEvents 100 |
Export-Csv -Path "C:\security_audit.csv" -NoTypeInformation
```
</details>

## 🛠️ Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/new-commands`)
3. Add your commands with proper documentation
4. Commit your changes (`git commit -m 'Add networking commands'`)
5. Push to the branch (`git push origin feature/new-commands`)
6. Open a Pull Request

### Contribution Guidelines

- Include detailed comments for each command
- Provide practical examples
- Test all commands before submitting
- Follow PowerShell best practices
- Group related commands together

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 👤 Author

**Jaquan Watson**
- GitHub: [@jaquanwatson](https://github.com/jaquanwatson)
- LinkedIn: [jaquanwatson](https://linkedin.com/in/jaquanwatson)
- Email: jqwatson96@gmail.com

---

<div align="center">

⭐ **Found this useful? Star this repository!** ⭐

</div>
Loading