Improve Documentation and VSCode Support #76

Xeratec · 2025-05-15T15:26:40Z

This PR introduces multi-branch GitHub Pages support to avoid overwriting existing documentation with each push, and improves the integration with Visual Studio Code to simplify debugging workflows. It also extends the documentation with a tutorial on using the debug print topology pass and the introspective code transformation (see #75).

Furthermore, this PR cleans up the compilation flow for PULP and Siracusa by disabling verbose build output by default. Users can still increase verbosity using the -v flag, for example:

python testRunner_siracusa.py -t Tests/Adder  -vvv

VS Code Support

To streamline development in Visual Studio Code, the build system now creates symlinks from the most recent build directory and generated source files (e.g., generated C files and deployStates) into a unified TEST_RECENT folder. This enables IntelliSense and other language features by pointing VSCode to the generated compile_commands.json, facilitating easier navigation and debugging.

Multi Branch Support

The workflow supports multi-branch GitHub Pages, enabling documentation for different branches to be deployed side-by-side. This allows maintaining documentation for various development stages (e.g., main, feature branches, and PR-specific previews). Each branch’s documentation is hosted under its respective path. For example:

The default branch (main) is deployed to the root of the GitHub Pages site.
(e.g. https://pulp-platform.github.io/Deeploy/)
Other branches, such as feature branches, are deployed under sub-paths corresponding to their branch names.
(e.g. https://pulp-platform.github.io/Deeploy/branch/devel)

An example documentation for this branch can be previewed here.

Added

Tutorial section in the documentation
Guide on using the debug print topology pass and code transformation
VSCode configuration files for improved IDE support
Multi-branch GitHub Pages deployment support

Changed

Updated README.md description to use a persistent development container
Symlinking of the latest build and source files into TEST_RECENT
Disabled CMAKE_VERBOSE_MAKEFILE by default for cleaner builds.

Fixed

Removed unsupported -MMD compiler flag in LLVM-based toolchains.

PR Merge Checklist

The PR is rebased on the latest devel commit and pointing to devel.
Your PR reviewed and approved.
All checks are passing.
The CHANGELOG.md file has been updated.
If the docker was modified, change back its link after review.
Merge Fix Debug Print Topology Pass and Code Transformation #75 and rebase

docs/tutorials/debugging.rst

cmake/pulp/toolchain_llvm.cmake

.vscode/launch.json

Xeratec · 2025-05-19T16:32:14Z

Also fixed a typo and added the --platform flag, which is required to use the container on Apple Silicon. In the future, I suggest we look into building an ARM container. See 59165d6

Victor-Jung

LGTM. Can you open an issue for the ARM container?

Xeratec · 2025-05-19T17:34:16Z

LGTM. Can you open an issue for the ARM container?

Done in #77.

This release contains major architectural changes, new platform support, enhanced simulation workflows, floating-point kernel support, training infrastructure for CCT models, memory allocation strategies, and documentation improvements. After merging this into `main`, the release process will proceed with: - Pushing a Git tag for the release after merging this PR - Creating a GitHub release with the prepared tag. Note: Since the release tag references the Docker container tagged with the release tag (`ghcr.io/pulp-platform/deeploy:v0.2.0`), the CI will initially fail. The Deeploy Docker image must be built after the release PR is merged and the CI restarted. ### List of Pull Requests - Prepare v0.2.0 release [#102](#102) - Add Luka as Code Owner [#101](#101) - Fix CI, Docker Files, and Documentation Workflow [#100](#100) - Chimera Platform Integration [#96](#96) - Add Tutorial and Refactor README [#97](#97) - Reduce Mean Float Template [#92](#92) - Reshape Memory Freeing and Generic Float GEMM Fixes [#91](#91) - Prepare for Release and Separate Dependencies [#90](#90) - Fix input offsets calculation [#89](#89) - Move PULP SDK to main branch/fork [#88](#88) - Finite Lifetime for IO Tensors [#51](#51) - Improved Memory Visualization and Multi-Layer Tiling Profiling [#56](#56) - Fix Linting in CI and Reformat C Files [#86](#86) - Fix Broken CMake Flow For pulp-sdk [#87](#87) - Refactor Changelog For Release [#85](#85) - ARM Docker Container and Minor Bug Fix [#84](#84) - Added Kernel for Generic Float DW Conv2D [#63](#63) - Autoselect Self-Hosted Runners if the Action is on Upstream [#81](#81) - TEST_RECENT linking on MacOS [#78](#78) - Add RV32IMF Picolibc support for Siracusa platform [#66](#66) - Improve Documentation and VSCode Support [#76](#76) - Debug Print Topology Pass and Code Transformation [#75](#75) - Find all subdirectories of Deeploy when installing with pip install [#70](#70) - Add milestone issue template [#71](#71) - Bunch of fixes and changes [#58](#58) - Add SoftHier platform [#65](#65) - rv32imf_xpulpv2 ISA support for Siracusa platform [#64](#64) - One LLVM To Compile Them All [#60](#60) - One GVSoC to Simulate Them All [#59](#59) - Add Support for CCT Last Layer Training with Embedding Dim 8-128 [#55](#55) - Add CCT Classifier Training Support [#53](#53) - L3 Bugs: DMA Struct Datatype and Maxpool Margin Error [#45](#45) - DeepQuant Quantized Linear Support [#54](#54) - Implemented Dequant Layer for Generic and Siracusa [#52](#52) - Infinite Lifetime Buffers Considered in Tiling & Memory Allocation (+ Visualization) [#44](#44) - Implemented Quant Layer for Generic and Siracusa [#49](#49) - Increase maximal Mchan DMA transfer sizes from 64KiB to 128KiB [#47](#47) - Add MiniMalloc and Decouple Memory Allocation and Tiling [#40](#40) - Float CCT Bugs on L3 [#37](#37) - Memory Allocation Strategies and Visualization [#36](#36) - Add CODEOWNERS [#42](#42) - Add Tiling Support to All CCT Kernels and Fix CCT Operators on Siracusa Platform for L2 [#35](#35) - Add Fp gemm and Softmax for Snitch platform [#31](#31) - Add Float Kernels for CCT [#29](#29) - documentation deployment [#34](#34) - main.c Float Cast Bugs [#28](#28) - Add Float GEMM on PULP with Tiling [#26](#26) - Add Float Support & Float GEMM for Generic [#25](#25) - GVSOC support for the Snitch Cluster platform [#23](#23) - Snitch Cluster Tiling Support [#22](#22) - Snitch support integration [#14](#14) - Update bibtex citation [#20](#20) - the PR template location, bump min python to 3.10, change install command [#17](#17) - Add pre-commit for python formatting [#15](#15) - FP integration (v2) [#12](#12) - shell for sequential tests of Generic, Cortex, and Mempool platforms [#11](#11) - Add issue templates [#10](#10) - Minor CI and Readme Improvements [#8](#8) - Fix GHCR Link for Docker Build [#7](#7) - neureka's ccache id [#6](#6) - GitHub-based CI/CD Flow [#4](#4) - Generic Softmax Kernel [#2](#2) - Port GitLab CI [#1](#1)

Xeratec self-assigned this May 15, 2025

Xeratec added Documentation Improvements or additions to documentation Feature Addition of new features labels May 15, 2025

Xeratec force-pushed the pr/improve_debugging branch from fcea305 to 2efeaad Compare May 15, 2025 15:29

Xeratec added 5 commits May 18, 2025 14:54

Improve documentation

3d455b3

Improve debug functionality with VSCode

5a01f40

Improve compilation flow

fb9fc07

Supports multi-branch GitHub Pages

3668180

Update Changelog

a2e71b7

Xeratec force-pushed the pr/improve_debugging branch from 9013ea6 to a2e71b7 Compare May 18, 2025 12:56

Xeratec changed the title ~~[Draft] Improve Documentation and VSCode Support~~ Improve Documentation and VSCode Support May 18, 2025

Xeratec marked this pull request as ready for review May 18, 2025 12:58

Xeratec requested a review from Victor-Jung as a code owner May 18, 2025 12:58

Victor-Jung requested changes May 19, 2025

View reviewed changes

docs/tutorials/debugging.rst Show resolved Hide resolved

cmake/pulp/toolchain_llvm.cmake Show resolved Hide resolved

.vscode/launch.json Show resolved Hide resolved

.vscode/launch.json Outdated Show resolved Hide resolved

Xeratec added 2 commits May 19, 2025 18:28

Implemented Feedback for PR

2237135

Small fix for Apple Silicon and Typo

59165d6

Victor-Jung approved these changes May 19, 2025

View reviewed changes

Xeratec merged commit 119fb29 into pulp-platform:devel May 19, 2025
122 checks passed

Xeratec deleted the pr/improve_debugging branch May 20, 2025 07:46

Xeratec mentioned this pull request Jul 8, 2025

Release v0.2.0 #103

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Improve Documentation and VSCode Support #76

Improve Documentation and VSCode Support #76

Uh oh!

Xeratec commented May 15, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Xeratec commented May 19, 2025 •

edited

Loading

Uh oh!

Victor-Jung left a comment

Uh oh!

Xeratec commented May 19, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Improve Documentation and VSCode Support #76

Improve Documentation and VSCode Support #76

Uh oh!

Conversation

Xeratec commented May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

VS Code Support

Multi Branch Support

Added

Changed

Fixed

PR Merge Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Xeratec commented May 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Victor-Jung left a comment

Choose a reason for hiding this comment

Uh oh!

Xeratec commented May 19, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Xeratec commented May 15, 2025 •

edited

Loading

Xeratec commented May 19, 2025 •

edited

Loading