diff --git a/docs/intro.md b/docs/intro.md index a6964a0..2424d94 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -101,46 +101,13 @@ to orchestrate their build process. * [ICU4N](https://github.com/NightOwl888/ICU4N) * [RandomizedTesting](https://github.com/NightOwl888/RandomizedTesting) -## Documentation Guide +## Next Steps -### Getting Started +Ready to start using psake? Here's what to do next: -New to psake? Start here: +1. **[Install psake](/docs/tutorial-basics/installing)** - Get psake set up on your system +2. **[Run your first build](/docs/tutorial-basics/run-psake)** - Create and execute your first psake script +3. **[Explore the Guides](/docs/tutorial-basics/default-build-files)** - Learn best practices and advanced techniques +4. **[Check the Command Reference](/docs/commands/Invoke-psake)** - Look up specific commands and their parameters -- **[Installing psake](/docs/tutorial-basics/installing)** - Installation methods and prerequisites -- **[Running psake](/docs/tutorial-basics/run-psake)** - Your first psake build -- **[Tasks](/docs/tutorial-basics/tasks)** - Understanding tasks and dependencies -- **[Parameters and Properties](/docs/tutorial-basics/parameters-properties)** - Configuring your builds - -### Build Type Examples - -Learn how to use psake with different project types: - -- **[.NET Solutions](/docs/build-types/dot-net-solution)** - Building .NET projects with MSBuild -- **[Node.js Projects](/docs/build-types/nodejs)** - npm, TypeScript, and Webpack builds -- **[Docker Builds](/docs/build-types/docker)** - Building and publishing Docker images - -### CI/CD Integration - -Integrate psake with your CI/CD pipeline: - -- **[GitHub Actions](/docs/ci-examples/github-actions)** - Complete GitHub Actions setup -- **[Azure Pipelines](/docs/ci-examples/azure-pipelines)** - Azure DevOps integration -- **[GitLab CI](/docs/ci-examples/gitlab-ci)** - GitLab CI/CD configuration - -### Troubleshooting - -Having issues? Check these resources: - -- **[Common Errors](/docs/troubleshooting/common-errors)** - Solutions to frequent problems -- **[FAQ](/docs/troubleshooting/faq)** - Frequently asked questions -- **[Debugging Guide](/docs/troubleshooting/debugging-guide)** - Debugging build scripts - -### Reference - -Quick reference and comprehensive documentation: - -- **[Glossary](/docs/reference/glossary)** - Definitions of psake terms and concepts -- **[Cheat Sheet](/docs/reference/cheat-sheet)** - Quick reference for common patterns -- **[Configuration Reference](/docs/reference/configuration-reference)** - All configuration options -- **[Exit Codes](/docs/reference/exit-codes)** - Understanding exit codes in CI/CD +Need help? Visit our [Troubleshooting](/docs/troubleshooting/common-errors) section or join the [PowerShell Discord](https://aka.ms/psdiscord) #psake channel. diff --git a/docs/tutorial-basics/getting-help.md b/docs/tutorial-basics/getting-help.md index 0c12465..4c851ff 100644 --- a/docs/tutorial-basics/getting-help.md +++ b/docs/tutorial-basics/getting-help.md @@ -1,65 +1,100 @@ --- -description: Learn how to get help on your psake tasks +description: Learn how to get help with psake - built-in documentation and community support sidebar_position: 3 --- # Getting Help -You can also use the PowerShell command `Get-Help` on the `Invoke-psake` -function to get more detailed help. +## Built-in Help -```powershell -# First import the psake.psm1 file +### View Available Tasks -Import-Module .\psake.psm1 +To see a list of all tasks defined in your psake build script, use the `-Docs` parameter: -Get-Help Invoke-psake -full +```powershell +Invoke-psake -Docs ``` -To list functions available in the psake module: +This will print the current tasks list from your psake file, showing all available tasks and their descriptions. + +### PowerShell Help System + +You can use the PowerShell `Get-Help` command on the `Invoke-psake` function to get detailed help: ```powershell -C:\Software\psake> Get-Command -module psake - -CommandType Name Definition ------------ ---- ---------- -Function Assert ... -Function Exec ... -Function FormatTaskName ... -Function Include ... -Function Invoke-psake ... -Function Properties ... -Function Task ... -Function TaskSetup ... -Function TaskTearDown ... +# First import the psake module +Import-Module psake + +# View full help for Invoke-psake +Get-Help Invoke-psake -Full ``` -To get example usage for individual functions in the psake PowerShell module, -use Get-Help, For example: +### List Available Commands + +To see all functions available in the psake module: ```powershell -C:\Software\psake> Get-Help Assert -examples +Get-Command -Module psake + +# Output: +# CommandType Name Definition +# ----------- ---- ---------- +# Function Assert ... +# Function Exec ... +# Function FormatTaskName ... +# Function Include ... +# Function Invoke-psake ... +# Function Properties ... +# Function Task ... +# Function TaskSetup ... +# Function TaskTearDown ... +``` + +### Get Examples for Specific Commands + +Use `Get-Help` with the `-Examples` parameter to see usage examples: -NAME - Assert +```powershell +Get-Help Assert -Examples + +# Output: +# NAME +# Assert +# +# SYNOPSIS +# Helper function for "Design by Contract" assertion checking. +# +# -------------------------- EXAMPLE 1 -------------------------- +# Assert $false "This always throws an exception" +# +# -------------------------- EXAMPLE 2 -------------------------- +# Assert ( ($i % 2) -eq 0 ) "$i is not an even number" +``` -SYNOPSIS - Helper function for "Design by Contract" assertion checking. +## Community Support - -------------------------- EXAMPLE 1 -------------------------- +Need help with your build scripts? The psake community is here to help! - C:\PS>Assert $false "This always throws an exception" +### Chat & Discussion +- **[PowerShell Discord](https://aka.ms/psdiscord)** - Join the #psake channel for real-time chat +- **[PowerShell Slack](https://aka.ms/psslack)** - Join the #psake channel for team collaboration +- **[GitHub Discussions](https://github.com/orgs/psake/discussions)** - For long-form questions and discussions - This example always throws an exception +### Q&A +- **[Stack Overflow](https://stackoverflow.com/questions/tagged/psake)** - Search existing questions or ask new ones using the `psake` tag +### Report Issues +Found a bug or have a feature request? - -------------------------- EXAMPLE 2 -------------------------- +- **[GitHub Issues](https://github.com/psake/psake/issues)** - Report bugs or request features in the main psake repository - C:\PS>Assert ( ($i % 2) -eq 0 ) "%i is not an even number" +## Documentation +For comprehensive guides and reference materials: - This example may throw an exception if $i is not an even number -``` +- **[Command Reference](/docs/commands/Invoke-psake)** - Detailed documentation for all psake commands +- **[Troubleshooting](/docs/troubleshooting/common-errors)** - Solutions to common problems +- **[FAQ](/docs/troubleshooting/faq)** - Frequently asked questions diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 9b4c480..bb1652f 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -82,9 +82,21 @@ const config: Config = { items: [ { type: 'docSidebar', - sidebarId: 'tutorialSidebar', + sidebarId: 'gettingStartedSidebar', position: 'left', - label: 'Tutorial', + label: 'Get Started', + }, + { + type: 'docSidebar', + sidebarId: 'guidesSidebar', + position: 'left', + label: 'Guides', + }, + { + type: 'docSidebar', + sidebarId: 'referenceSidebar', + position: 'left', + label: 'Reference', }, { to: '/blog', label: 'Blog', position: 'left' }, { @@ -101,16 +113,16 @@ const config: Config = { title: 'Docs', items: [ { - label: 'Quick Start', + label: 'Get Started', to: '/docs/intro', }, { - label: 'Tutorial - Basics', - to: '/docs/tutorial-basics/installing', + label: 'Guides', + to: '/docs/tutorial-basics/default-build-files', }, { label: 'Command Reference', - to: '/docs/commands/Assert', + to: '/docs/commands/Invoke-psake', }, { label: 'Code of Conduct', diff --git a/sidebars.ts b/sidebars.ts index 43ccde1..21cc354 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1,5 +1,6 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; import commands from "./docs/commands/docusaurus.sidebar.js"; + /** * Creating a sidebar enables you to: - create an ordered group of docs @@ -11,26 +12,31 @@ import commands from "./docs/commands/docusaurus.sidebar.js"; Create as many sidebars as you want. */ const sidebars: SidebarsConfig = { - // By default, Docusaurus generates a sidebar from the docs folder structure - tutorialSidebar: [ + // Getting Started - For newcomers and quick onboarding + gettingStartedSidebar: [ 'intro', + 'tutorial-basics/installing', + 'tutorial-basics/getting-help', + 'tutorial-basics/run-psake', + 'tutorial-basics/tasks', + 'tutorial-basics/parameters-properties', + ], + + // Guides - How-to guides, examples, and best practices + guidesSidebar: [ { type: 'category', - label: 'Tutorial - Basics', + label: 'Core Concepts', items: [ - 'tutorial-basics/installing', - 'tutorial-basics/getting-help', - 'tutorial-basics/run-psake', - 'tutorial-basics/tasks', - 'tutorial-basics/parameters-properties', 'tutorial-basics/default-build-files', 'tutorial-basics/how-to-fail-a-build', 'tutorial-basics/nested-build', + 'tutorial-advanced/structure-of-a-psake-build-script', ], }, { type: 'category', - label: 'Tutorial - Advanced', + label: 'Advanced Techniques', items: [ 'tutorial-advanced/access-functions-in-another-file', 'tutorial-advanced/build-script-resilience', @@ -39,13 +45,12 @@ const sidebars: SidebarsConfig = { 'tutorial-advanced/outputs-and-artifacts', 'tutorial-advanced/print-psake-task-name', 'tutorial-advanced/retry-rules', - 'tutorial-advanced/structure-of-a-psake-build-script', 'tutorial-advanced/variable-referencing', ], }, { type: 'category', - label: 'Build Types', + label: 'Build Type Examples', items: [ 'build-types/dot-net-solution', 'build-types/nodejs', @@ -54,7 +59,7 @@ const sidebars: SidebarsConfig = { }, { type: 'category', - label: 'CI Examples', + label: 'CI/CD Integration', items: [ 'ci-examples/github-actions', 'ci-examples/azure-pipelines', @@ -64,6 +69,10 @@ const sidebars: SidebarsConfig = { 'ci-examples/team-city', ] }, + ], + + // Reference - Command reference, troubleshooting, and lookup materials + referenceSidebar: [ { type: 'category', label: 'Command Reference', @@ -71,21 +80,21 @@ const sidebars: SidebarsConfig = { }, { type: 'category', - label: 'Troubleshooting', + label: 'Reference Materials', items: [ - 'troubleshooting/common-errors', - 'troubleshooting/faq', - 'troubleshooting/debugging-guide', + 'reference/configuration-reference', + 'reference/cheat-sheet', + 'reference/glossary', + 'reference/exit-codes', ] }, { type: 'category', - label: 'Reference', + label: 'Troubleshooting', items: [ - 'reference/glossary', - 'reference/cheat-sheet', - 'reference/configuration-reference', - 'reference/exit-codes', + 'troubleshooting/common-errors', + 'troubleshooting/faq', + 'troubleshooting/debugging-guide', ] }, { @@ -94,19 +103,6 @@ const sidebars: SidebarsConfig = { id: 'code_of_conduct' }, ], - - // But you can create a sidebar manually - /* - tutorialSidebar: [ - 'intro', - 'hello', - { - type: 'category', - label: 'Tutorial', - items: ['tutorial-basics/create-a-document'], - }, - ], - */ }; export default sidebars; diff --git a/src/css/custom.css b/src/css/custom.css index 3b9fa50..302fab4 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -13,6 +13,7 @@ --ifm-color-primary-light: #2e7637; --ifm-color-primary-lighter: #307b39; --ifm-color-primary-lightest: #35863e; + --ifm-background-color: #F8F9F5; --ifm-code-font-size: 95%; --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); }