Skip to content

Commit c7f0015

Browse files
Claudio-MerolaClaudio-Merola
authored
Merge pull request #302 from domalab/main
Comprehensive documentation system using MkDocs and Material theme, along with automation workflows for Azure Resource Inventory (ARI) and documentation deployment
2 parents 80e5f74 + a31046f commit c7f0015

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+4077
-387
lines changed

‎.github/PULL_REQUEST_TEMPLATE/documentation.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Documentation Update
2+
3+
## Description
4+
5+
This PR adds a comprehensive documentation system using MkDocs with the Material theme.
6+
7+
## Changes Made
8+
9+
- Added MkDocs with Material theme configuration
10+
- Created documentation structure with the following sections:
11+
- Getting Started (Installation and Quick Start)
12+
- User Guide (Basic Usage, Parameters, Common Scenarios)
13+
- Features (Excel Reports and more)
14+
- Advanced (Automation and Resource Types)
15+
- Added GitHub Actions workflow for automatic documentation deployment
16+
- Added local testing scripts (`test-docs.sh` and `test-workflow.sh`)
17+
18+
## Testing
19+
20+
- Documentation has been tested locally with `mkdocs serve`
21+
- GitHub workflow has been tested locally with `act`
22+
23+
## Deployment Instructions
24+
25+
1. Review the documentation content for accuracy and completeness
26+
2. Make any required adjustments to the content or structure
27+
3. Once merged, the GitHub workflow will deploy the documentation to GitHub Pages
28+
4. Enable GitHub Pages in repository settings:
29+
- Go to Settings > Pages
30+
- Select "GitHub Actions" as the source
31+
- The documentation will be available at `https://[organization].github.io/ARI/`
32+
33+
## Screenshots
34+
35+
(If applicable, add screenshots of the documentation site)
36+
37+
## Checklist
38+
39+
- [ ] Documentation content is accurate and up-to-date
40+
- [ ] All links work correctly
41+
- [ ] Documentation navigation is intuitive
42+
- [ ] GitHub workflow is correctly configured
43+
- [ ] MkDocs configuration is correctly set up
44+
- [ ] Documentation renders correctly in local testing

‎.github/workflows/azure-inventory.yml‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: Azure Resource Inventory
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
subscriptionId:
7+
description: 'Specific subscription ID (optional)'
8+
required: false
9+
default: '00000000-0000-0000-0000-000000000000'
10+
resourceGroup:
11+
description: 'Specific resource group (optional)'
12+
required: false
13+
default: 'test-rg'
14+
reportName:
15+
description: 'Custom report name (optional)'
16+
required: false
17+
default: 'TestInventory'
18+
19+
jobs:
20+
run-inventory:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- name: Checkout repository
24+
uses: actions/checkout@v3
25+
26+
# For local testing, we'll simulate the Azure login step
27+
- name: Simulate Azure Login
28+
run: |
29+
echo "Azure login simulated for local testing"
30+
31+
# For local testing with act, we'll simulate the module installation and ARI execution
32+
- name: Simulate ARI Installation and Run
33+
shell: bash
34+
run: |
35+
echo "Installing ARI modules (simulation for testing)"
36+
echo "Running Invoke-ARI with parameters:"
37+
echo "- ReportName: ${{ github.event.inputs.reportName }}"
38+
echo "- SubscriptionID: ${{ github.event.inputs.subscriptionId }}"
39+
echo "- ResourceGroup: ${{ github.event.inputs.resourceGroup }}"
40+
41+
# Create dummy report files
42+
mkdir -p ari-reports
43+
echo "This is a test Excel report" > ari-reports/test_report.xlsx
44+
echo "This is a test diagram file" > ari-reports/test_diagram.drawio
45+
46+
# List the created files
47+
echo "Created files:"
48+
ls -la ari-reports/
49+
50+
echo "Workflow execution completed successfully"
51+
52+
# Optional: Upload to Azure Storage
53+
# - name: Upload to Azure Storage
54+
# shell: pwsh
55+
# run: |
56+
# $storageAccount = "yourstorageaccount"
57+
# $container = "ari-reports"
58+
#
59+
# # Create the storage context
60+
# $ctx = New-AzStorageContext -StorageAccountName $storageAccount -UseConnectedAccount
61+
#
62+
# # Upload files to Azure Storage
63+
# Get-ChildItem -Path "$env:GITHUB_WORKSPACE/ari-reports" -File | ForEach-Object {
64+
# Set-AzStorageBlobContent -File $_.FullName -Container $container -Blob $_.Name -Context $ctx -Force
65+
# }
66+
67+
# Optional: Send email notification
68+
# - name: Send Email Notification
69+
# uses: dawidd6/action-send-mail@v3
70+
# with:
71+
# server_address: smtp.gmail.com
72+
# server_port: 465
73+
# username: ${{ secrets.EMAIL_USERNAME }}
74+
# password: ${{ secrets.EMAIL_PASSWORD }}
75+
# subject: Azure Resource Inventory Report
76+
# body: Azure Resource Inventory has completed. Reports are attached.
77+
# to: [email protected]
78+
# from: Azure Inventory <[email protected]>

‎.github/workflows/documentation.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Build and Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'docs/**'
9+
- 'mkdocs.yml'
10+
- '.github/workflows/documentation.yml'
11+
pull_request:
12+
branches:
13+
- main
14+
paths:
15+
- 'docs/**'
16+
- 'mkdocs.yml'
17+
- '.github/workflows/documentation.yml'
18+
workflow_dispatch:
19+
20+
jobs:
21+
build-and-deploy:
22+
runs-on: ubuntu-latest
23+
steps:
24+
- name: Checkout
25+
uses: actions/checkout@v3
26+
with:
27+
fetch-depth: 0
28+
29+
- name: Setup Python
30+
uses: actions/setup-python@v4
31+
with:
32+
python-version: '3.x'
33+
34+
- name: Install dependencies
35+
run: |
36+
python -m pip install --upgrade pip
37+
pip install -r requirements.txt
38+
39+
- name: Build MkDocs site
40+
run: mkdocs build
41+
42+
- name: Deploy (if on main branch)
43+
if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
44+
uses: peaceiris/actions-gh-pages@v3
45+
with:
46+
github_token: ${{ secrets.GITHUB_TOKEN }}
47+
publish_dir: ./site

‎.gitignore‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# PowerShell module specific
2+
*.psd1.backup
3+
*.psm1.backup
4+
*.ps1.backup
5+
*.ps1.bak
6+
*.psm1.bak
7+
*.psd1.bak
8+
9+
# PowerShell module output
10+
output/
11+
out/
12+
13+
# PowerShell Studio files
14+
*.psprojs
15+
*.psproj
16+
*.TempPoint.*
17+
18+
# PowerShell Gallery package
19+
*.nupkg
20+
21+
# PowerShell test results
22+
TestResults/
23+
TestResults.xml
24+
25+
# Pester test results
26+
coverage.xml
27+
coverage/
28+
29+
# PSScriptAnalyzer results
30+
PSScriptAnalyzer.results.xml
31+
32+
# MkDocs specific
33+
site/
34+
docs_build/
35+
__pycache__/
36+
*.py[cod]
37+
*$py.class
38+
*.so
39+
.Python
40+
env/
41+
build/
42+
develop-eggs/
43+
dist/
44+
downloads/
45+
eggs/
46+
.eggs/
47+
lib/
48+
lib64/
49+
parts/
50+
sdist/
51+
var/
52+
*.egg-info/
53+
.installed.cfg
54+
*.egg
55+
56+
# Python virtual environment
57+
venv/
58+
ENV/
59+
docs-venv/
60+
.venv/
61+
62+
# IDE specific files
63+
.idea/
64+
.vscode/
65+
*.swp
66+
*.swo
67+
*~
68+
.DS_Store
69+
Thumbs.db
70+
71+
# Logs
72+
logs/
73+
*.log
74+
npm-debug.log*
75+
yarn-debug.log*
76+
yarn-error.log*
77+
78+
# Runtime data
79+
pids
80+
*.pid
81+
*.seed
82+
*.pid.lock
83+
84+
# Temporary files
85+
tmp/
86+
temp/
87+
.tmp/
88+
.temp/
89+
90+
# Excel temporary files
91+
~$*.xlsx
92+
~$*.xls
93+
~$*.xlsm
94+
~$*.xlsb
95+
96+
# Drawio temporary files
97+
.$*.drawio.bkp
98+
.$*.drawio.dtmp
99+
100+
# Azure Resource Inventory specific
101+
ari-reports/
102+
*.xlsx
103+
*.drawio
104+
!docs/images/*.xlsx
105+
!docs/images/*.drawio
106+
107+
# Local test files
108+
local-test/
109+
test-results/
110+
111+
# Azure credentials and secrets
112+
*.publishsettings
113+
*.pfx
114+
*.p12
115+
*.pem
116+
*.key
117+
*.crt
118+
*.cer
119+
*.azureauth
120+
azureauth.json
121+
*.azurecredentials
122+
*credentials*.json
123+
*secrets*.json
124+
*connection*.json
125+
126+
# Azure CLI and PowerShell Azure Module cache
127+
.azure/
128+
.azcli/
129+
130+
# Terraform files
131+
.terraform/
132+
*.tfstate
133+
*.tfstate.backup
134+
*.tfvars
135+
136+
# Bicep files
137+
*.bicepparam
138+
139+
# Act (GitHub Actions local testing)
140+
.actrc
141+
.secrets
142+
143+
# Docker
144+
.docker/
145+
Docker.*.env
146+
147+
# Node.js (for potential web components)
148+
node_modules/
149+
150+
# Jupyter Notebooks (for potential data analysis)
151+
.ipynb_checkpoints/
152+
*.ipynb
153+
154+
# R files (for potential data analysis)
155+
.Rproj.user/
156+
.Rhistory
157+
.RData
158+
.Ruserdata
159+
160+
# macOS extended attributes
161+
._*
162+
163+
# Windows shortcuts
164+
*.lnk
165+
166+
# Windows thumbnail cache
167+
ehthumbs.db
168+
ehthumbs_vista.db
169+
170+
# Windows folder config
171+
Desktop.ini
172+
173+
# Windows Recycle Bin used on file shares
174+
$RECYCLE.BIN/
175+
176+
# Windows Installer files
177+
*.cab
178+
*.msi
179+
*.msm
180+
*.msp
181+
182+
# Backup files created by various editors
183+
*.bak
184+
*.gho
185+
*.ori
186+
*.orig
187+
*.tmp
188+
189+
# Archive files
190+
*.7z
191+
*.jar
192+
*.rar
193+
*.zip
194+
*.gz
195+
*.tgz
196+
*.bzip
197+
*.bz2
198+
*.xz
199+
*.lzma
200+
*.cab
201+
*.iso
202+
*.tar
203+
204+
# Compiled source
205+
*.com
206+
*.class
207+
*.dll
208+
*.exe
209+
*.o
210+
*.obj
211+
212+
# Dependency directories
213+
vendor/

0 commit comments

Comments
 (0)