[S] Documentation signpost added (#4501)

* * added new documentation readme page which contains categorized links to all dother documentation pages in this repository with brief description * documentaiton section in repo readme file updated with a link to documentation readme * lint compilation errors fixed * more links to documentation pages added to the signpost --------- Co-authored-by: Kuba Drazka <[email protected]>
dotnet · Oct 15, 2024 · fd0d92d · fd0d92d
1 parent b5f1f9e
commit fd0d92d
Show file tree

Hide file tree

Showing 6 changed files with 50 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -12,10 +12,7 @@ Finding these benchmarks in a separate repository might be surprising. Performan
 
 ## Documentation
 
-* [Microbenchmarks Guide](./src/benchmarks/micro/README.md) for information on running our microbenchmarks
-* [Scenario Tests Guide](./docs/scenarios-workflow.md) for information on running our real-world scenario benchmarks
-* [Benchmarking workflow for dotnet/runtime repository](./docs/benchmarking-workflow-dotnet-runtime.md) for information on benchmarking local [dotnet/runtime](https://github.com/dotnet/runtime) builds
-* [Profiling workflow for dotnet/runtime repository](./docs/profiling-workflow-dotnet-runtime.md) for information on profiling local [dotnet/runtime](https://github.com/dotnet/runtime) builds
+See the [documentation signpost](./docs/readme.md).
 
 ## Contributing to Repository
 

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,42 @@
+# .NET Performance Repository Documentation Readme
+
+The documentation in this repo is organized into the following sections:
+
+## Getting Started
+
+- [Prerequisites](prerequisites.md) - Information on what you need to get started.
+- [Perf report walkthrough](perfreport-walkthrough.md) - This document describes Performance Report Advanced Features.
+- [Crank to Helix workflow](crank-to-helix-workflow.md) - Information on how to schedule performance tests to be run on Helix machines using Crank (instead of running locally).
+- [Profiling workflow dotnet runtime](profiling-workflow-dotnet-runtime.md) - This doc explains how to profile local [dotnet/runtime](https://github.com/dotnet/runtime) builds and it's targetted at [dotnet/runtime](https://github.com/dotnet/runtime) repository contributors.
+- [Pipeline templates](../eng/common/template-guidance.md) - Information on azure yml pipelines.
+
+## Running Benchmarks
+
+- [BenchmarkDotNet](benchmarkdotnet.md) - Information of how to run benchmarks using BenchmarkDotNet tool and interpret results.
+- [Benchmarking workflow](benchmarking-workflow-dotnet-runtime.md) - Information about the (micro)benchmarks for the [dotnet/runtime](https://github.com/dotnet/runtime) in this repository.
+- [Microbenchmarks Guide](../src/benchmarks/micro/README.md) for information on running our microbenchmarks.
+- [Micro Benchmarks of .NET Runtime(s)](../src/benchmarks/micro/README.md) - Information on benchmarks of .NET Runtime(s).
+- [Microbenchmarks design guidelines](microbenchmark-design-guidelines.md) - Detailed guidelines on how to design and write microbenchmarks.
+- [benchmarks_local.py script guide](../src/scripts/BENCHMARKS_LOCAL_README.md) - Description of a script for testing the performance of the different dotnet/runtime build types locally.
+- [ResultsComparer tool](../src/tools/ResultsComparer/README.md) - Information on tool which allows for easy comparison of provided benchmark results.
+- [Serializers Benchmarks](../src/benchmarks/micro/Serializers/README.md) - Information on benchmarks of the most popular serializers.
+- [bepuphysics2 Benchmarks](../src/benchmarks/real-world/bepuphysics2/README.md) - Information on benchmarks of bepuphysics2 library.
+- [Microsoft.ML Benchmarks datasets](../src/benchmarks/real-world/Microsoft.ML.Benchmarks/Input/README.md) - Information on datasets used for benchmarking of the Microsoft.ML library.
+- [Benchmarks run in PowerShell](../src/benchmarks/real-world/PowerShell.Benchmarks/README.md) - Information on performance tests for different pieces of the library run using PowerShell.
+
+### GC Benchmarks
+
+- [ASP.NET Benchmarks errors](../src/benchmarks/gc/GC.Infrastructure/docs/ASPNETBenchmarks.md) - Information on main types of errors while running ASP.NET Benchmarks using crank.
+- [Testing GC.Infrastructure](../src/benchmarks/gc/GC.Infrastructure/README.md) - Information on testing GC.Infrastructure.
+- [GC.Analysis.API](../src/benchmarks/gc/GC.Infrastructure/GC.Analysis.API/README.md) - Information on conducting GC, CPU and Threading analysis using .NET Interactive notebooks.
+- [GC.Infrastructure Notebooks](../src/benchmarks/gc/GC.Infrastructure/Notebooks/README.md) - Information on notebooks that either provide examples or functionality for specialized analysis
+- [Benchmark Analysis](../src/benchmarks/gc/GC.Infrastructure/Notebooks/BenchmarkAnalysis.md) - Information on a notebook which contains code for producing charts (and soon, tables) for GC benchmarks. It can currently process data
+from the ASP.NET benchmarks obtained using crank as well as ETL data.
+
+## Running Scenarios
+
+- [Scenarios workflow](scenarios-workflow.md) - An introduction of how to run scenario tests.
+- [Basic scenarios](basic-scenarios.md) - Specific instruction of how to run various basic scenarios.
+- [Blazor scenarios](blazor-scenarios) - Specific instruction of how to run _New Blazorwasm Template Size On Disk_ scenarios.
+- [Cross-gen scenarios](crossgen-scenarios.md) - Specific instruction of how to run _crossgen_ scenarios.
+- [SDK scenarios](sdk-scenarios.md) - Specific instruction of how to run _SDK Build Throughput Scenario_ scenarios.
diff --git a/docs/blazor-scenarios.md b/docs/blazor-scenarios.md
@@ -82,6 +82,7 @@ Same instruction of [Step 4 in Scenario Tests Guide](scenarios-workflow.md#step-
 ## Command Matrix
 
 For the purpose of quick reference, the commands can be summarized into the following matrix:
+
 | Scenario                            | Asset Directory | Precommand                                                  | Testcommand                                                       | Postcommand | Supported Framework | Supported Platform |
 |-------------------------------------|-----------------|-------------------------------------------------------------|-------------------------------------------------------------------|-------------|---------------------|--------------------|
 | SOD - New Blazor Template - Publish | blazor          | pre.py publish --msbuild "/p:_TrimmerDumpDependencies=true" | test.py sod --scenario-name "SOD - New Blazor Template - Publish" | post.py     | net7.0; net8.0      | Windows;Linux      |

diff --git a/docs/crossgen-scenarios.md b/docs/crossgen-scenarios.md
@@ -188,6 +188,7 @@ python3 post.py
 ## Command Matrix
 
 For the purpose of quick reference, the commands can be summarized into the following matrix:
+
 | Scenario                               | Asset Directory | Precommand                                                                     | Testcommand                                                                       | Postcommand | Supported Framework | Supported Platform      |
 |----------------------------------------|-----------------|--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|-------------|---------------------|-------------------------|
 | Crossgen Throughput                    | crossgen        | N/A                                                                            | test.py crossgen --core-root \<path to Core_Root> --single \<assembly name>       | post.py     | N/A                 | Windows-x64;Windows-x86 |

diff --git a/eng/common/template-guidance.md b/eng/common/template-guidance.md
@@ -1,6 +1,6 @@
 # Overview
 
-Arcade provides templates for public (`/templates`) and 1ES pipeline templates (`/templates-official`) scenarios.  Pipelines which are required to be managed by 1ES pipeline templates should reference `/templates-offical`, all other pipelines may reference `/templates`.
+Arcade provides templates for public (`/templates`) and 1ES pipeline templates (`/templates-official`) scenarios. Pipelines which are required to be managed by 1ES pipeline templates should reference `/templates-offical`, all other pipelines may reference `/templates`.
 
 ## How to use
 
@@ -12,7 +12,7 @@ Basic guidance is:
 
 See [azure-pipelines.yml](../../azure-pipelines.yml) (templates-official example) or [azure-pipelines-pr.yml](../../azure-pipelines-pr.yml) (templates example) for examples.
 
-#### The `templateIs1ESManaged` parameter
+### The `templateIs1ESManaged` parameter
 
 The `templateIs1ESManaged` is available on most templates and affects which of the variants is used for nested templates. See [Development Notes](#development-notes) below for more information on the `templateIs1ESManaged1 parameter.
 
@@ -23,6 +23,7 @@ The `templateIs1ESManaged` is available on most templates and affects which of t
 1ES pipeline templates impose a policy where every publish artifact execution results in additional security scans being injected into your pipeline.  When using `templates-official/jobs/jobs.yml`, Arcade reduces the number of additional security injections by gathering all publishing outputs into the [Build.ArtifactStagingDirectory](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#build-variables-devops-services), and utilizing the [outputParentDirectory](https://eng.ms/docs/cloud-ai-platform/devdiv/one-engineering-system-1es/1es-docs/1es-pipeline-templates/features/outputs#multiple-outputs) feature of 1ES pipeline templates.  When implementing your pipeline, if you ensure publish artifacts are located in the `$(Build.ArtifactStagingDirectory)`, and utilize the 1ES provided template context, then you can reduce the number of security scans for your pipeline.
 
 Example:
+
 ``` yaml
 # azure-pipelines.yml
 extends:
@@ -59,7 +60,7 @@ Note: Multiple outputs are ONLY applicable to 1ES PT publishing (only usable whe
 
 ## Development notes
 
-**Folder / file structure**
+### Folder / file structure
 
 ``` text
 eng\common\

diff --git a/src/benchmarks/gc/GC.Infrastructure/GC.Analysis.API/README.md b/src/benchmarks/gc/GC.Infrastructure/GC.Analysis.API/README.md
@@ -7,7 +7,7 @@ This repository contains all the code responsible for conducting GC, CPU and Thr
 1. Install all dependencies by:
    1. [Installing VSCode](https://code.visualstudio.com/Download) - install vscode using the installer; downloading a zip file of the exe will result in issues with the ``Install.cmd`` script.
    2. [Installing the .NET6 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0)
-   3. Ensure you have Jupyter:
+   3. Ensure you have Jupyter (one of the following options):
       1. Install python using the Windows Store.
       2. Manually install Jupyter:
          1. ``pip`` is in your PATH: