DOC: Updating Getting Started Docs#1540
Merged
rlundeen2 merged 31 commits intomicrosoft:mainfrom Mar 26, 2026
Merged
Conversation
- Add 'Getting Started' section to landing page with Install + Configure steps - Create new Quick Start Guide (doc/setup/quick_start.md) as consolidated zero-to-running page with multi-provider examples and initializer explanation - Make populating_secrets.md provider-agnostic with tabbed examples for OpenAI, Azure, Ollama, Groq, and OpenRouter - Add 'Recommended Defaults' initializer table to pyrit_conf.md explaining what each initializer registers and why pyrit_scan needs them - Add 'Next: Configure' callouts to install pages (1a, 1b) - Restructure myst.yml TOC with Quick Start as the Setup entry point - Add guidance header to .env_example noting most users need only 3 vars Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Create doc/setup/configuration.md grouping secrets and conf file - Create doc/setup/faq.md grouping Jupyter setup and Azure SQL - Restructure myst.yml TOC with Configuration and FAQ as parent entries - Rename 'Install PyRIT Library' to 'Install PyRIT' in 1a_install_uv.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Trim Install PyRIT page to just a decision guide with cards - Extract local pip/uv instructions to new install_local.md sub-page - Expand Configuration page into a decision guide with 2 cards - Update landing page: local install links to install_local.md, configure section reduced to 2 cards (Minimal + Config File), removed Advanced Options card - Add install_local.md to myst.yml TOC Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Install PyRIT page: - Now shows 4 cards matching the landing page: Docker, Local Pip/uv (users), DevContainers, Local uv Dev (contributors) Configuration section: - New minimal_setup.md: try PyRIT with just 2 env vars, no files needed - Simplified populating_secrets.md: just provider tabs and .env location - Expanded pyrit_conf.md: now includes env precedence, .env.local overrides, and auth options (moved from populating_secrets) - Fleshed out configuration.md: overview with mermaid diagram, 3 cards, and 'What Goes Where' reference table Landing page: - Configure section now has 3 cards: Minimal Setup, Populating Secrets, Config File (Recommended) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ting - Rename 'Quick Start Guide' to 'Getting Started' - Move contributing/1a_install_uv, 1b_install_devcontainers, 1c_install_conda under Install PyRIT in the TOC (navbar) so all install options are together - Renumber contributing files: 2_git -> 1_git, 3_incorporating_research -> 2_incorporating_research, etc. (start at 1 since install moved out) - Update titles inside each renamed file to match new numbers - Fix cross-references to renamed files (running_tests, notebooks) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Rename top nav 'Setup' to 'Getting Started' - Remove standalone conda and minimal_setup pages (merged content) - Exactly 4 install sub-pages: Local, Docker, DevContainers, Local uv Dev - Configuration landing inlines minimal setup content - Landing page has 2 configure cards (Secrets, Config File) - Fix stale cross-references to removed pages Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Rename files for clean URLs: - 1a_install_uv.md → install.md (/setup/install) - 1b_install_docker.md → install_docker.md - 1b_install_devcontainers.md → install_devcontainers.md - 1a_install_uv.md → install_local_dev.md Consistent titles and order everywhere: 1. User Docker Installation 2. User Local Installation 3. Contributor Docker Installation 4. Contributor Local Installation Landing page, install landing page, and navbar all match. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Rename doc/setup/ to doc/getting_started/ matching nav title - Move contributor install pages into getting_started/ (no longer split across contributing/) - Remove stale contributing/1c_install_conda.md - Update all cross-references and myst.yml paths - URLs now match navbar: /getting_started/install, /getting_started/install-docker, etc. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Getting Started: now a clean section overview with cards linking to Install PyRIT, Configure PyRIT, and FAQ - Configure PyRIT: renamed from 'Configuration', now has quickest-start inline (env vars + 3 lines of Python) plus cards for Populating Secrets and Configuration File for persistent setup - Moved step-by-step quick_start content into sub-pages where needed - Updated all cross-references to use 'Configure PyRIT' naming Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…next steps, rename FAQ to Troubleshooting - Rename quick_start.md → README.md so both nav and sidebar link to /getting_started/readme - Move 'Who Should Use' guidance from install sub-pages to install.md landing cards - Trim sub-pages to brief intros instead of duplicating decision guidance - Standardize 'Next Step' footers: install pages → Configure PyRIT, config pages → cookbooks/CLI - Rename FAQ → Troubleshooting, move deployment/ files under getting_started/ - Remove standalone deployment/ section from TOC - Delete deployment/README.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Landing page fixes: - Remove [@citation] keys that generated References section at bottom - Remove section break between Key Capabilities and Getting Started (less spacing) - Fix Getting Started nav URL: /getting_started/readme → /getting-started/readme Extract troubleshooting from install pages into dedicated pages: - troubleshooting_docker.md (JupyterLab, permissions, env files, build) - troubleshooting_devcontainers.md (build fails, extensions, performance) - troubleshooting_local_dev.md (uv not found, imports, dependencies, modules) - Each install page now links to its troubleshooting page - All 3 new pages added to Troubleshooting section in TOC Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…cing - Add User Guide landing page with cards for all 11 sections - Remove 'Advantages over Other Methods' and 'Additional Resources' from install_local_dev.md (out of place) - Group troubleshooting in navbar matching landing page structure: Installation Issues, Setup Issues, Model Deployment Guides - Remove 'Before you begin, ensure you are set up...' boilerplate from 52 .py files and 1 .md file (noise; Getting Started section is prominent) - Add --- horizontal rule between Key Capabilities and Getting Started on landing page for moderate spacing - Remove inline citations from landing page (no more References section) - Fix Getting Started nav URL to use hyphens Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Configure pages: replace random Cookbooks/Targets/Scenarios/CLI links with single User Guide link (the natural next destination) - populating_secrets: keep pyrit_conf cross-link + User Guide - install_docker: move Next Step from mid-page to before Troubleshooting, remove stray cookbook link - install_devcontainers: move Next Step from mid-page to after Common DevContainer Operations, before Troubleshooting Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Create getting_started/troubleshooting/ subdirectory to match navbar - Move all 15+ troubleshooting files with cleaner names (drop prefixes) - Merge 'Setup Issues' group into 'Installation & Setup Issues' (2 groups instead of 3): docker, devcontainers, local_dev, jupyter_setup, azure_sql_db - Delete troubleshooting_setup.md (absorbed into installation.md) - Update myst.yml TOC paths - Fix cross-references from install pages and contributing - Fix relative asset/link paths in moved .py and .md files Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Regenerated 25 .ipynb files from their .py sources using jupytext to sync the 'Before you begin' preface removal that was previously applied only to .py files. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- docker/README.md: update 4 refs from doc/setup/1b_install_docker.md to doc/getting_started/install_docker.md - install_devcontainers.md: fix image path and 7_notebooks.md link to point to ../contributing/ - troubleshooting/docker.md: fix install_docker.md link (up one level) - code/setup/1_configuration.py: fix pyrit_conf.md link from setup/ to getting_started/; regenerated matching .ipynb Skipped: azure.microsoft.com/free (works fine, false positive) and mistralai anchor ref (valid MyST cross-reference, not a broken link) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- platform.openai.com/api-keys: requires auth, blocks automated requests - azure.microsoft.com/free/: Azure blocks automated requests - mistralai_mixtral_8x7b_instruct_v0_1: valid MyST cross-reference anchor Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Previous jupytext run used --to ipynb without --update, stripping cell outputs. Fixed by restoring .ipynb from main then regenerating with --update to preserve outputs while syncing source changes. Also restored 0_auxiliary_attacks.py and 1_gcg_azure_ml.py which were accidentally modified. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…erplate Restored from main to recover cell outputs, then manually removed the 'Before you begin' line from the markdown cell. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Restructured as Option 1 (uv, recommended) and Option 2 (conda) for contributors who prefer conda environment management. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Added sections for conda activation, package conflicts, and Jupyter kernel issues to match the conda option added to install_local_dev.md. Restructured existing uv items under a 'uv Issues' heading. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
adrian-gavrila
left a comment
adrian-gavrila
left a comment
There was a problem hiding this comment.
Overall looks great! Added a couple of comments for clarity
Co-authored-by: Adrian Gavrila <50029937+adrian-gavrila@users.noreply.github.com>
…deen2/PyRIT into users/rlundeen/2026_03_docs
adrian-gavrila
approved these changes
Mar 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Restructures the doc site so the install → configure → use path is clear and intuitive.