diff --git a/README.md b/README.md index c8460b03..514fca68 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ [![VS Code Marketplace](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpascal-lab.gallery.vsassets.io%2F_apis%2Fpublic%2Fgallery%2Fpublisher%2Fpascal-lab%2Fextension%2Fvide-ls%2Flatest%2Fassetbyname%2FMicrosoft.VisualStudio.Code.Manifest&query=%24.version&label=Marketplace&prefix=v&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTIzLjE1IDIuNTkgMTguMjEuMjFhMS40OSAxLjQ5IDAgMCAwLTEuNy4yOUw3LjA2IDkuMTEgMi45NCA1Ljk5YTEgMSAwIDAgMC0xLjI3LjA2TC4zMyA3LjI2YTEgMSAwIDAgMCAwIDEuNDhMMy45IDEyIC4zMyAxNS4yNmExIDEgMCAwIDAgMCAxLjQ4bDEuMzQgMS4yMWExIDEgMCAwIDAgMS4yNy4wNmw0LjEyLTMuMTIgOS40NSA4LjYxYTEuNDkgMS40OSAwIDAgMCAxLjcuMjlsNC45NC0yLjM4QTEuNSAxLjUgMCAwIDAgMjQgMjAuMDZWMy45NGExLjUgMS41IDAgMCAwLS44NS0xLjM1Wk0xOCAxNy40NSAxMC44MyAxMiAxOCA2LjU1djEwLjlaIi8%2BPC9zdmc%2B&logoColor=white&color=007ACC)](https://marketplace.visualstudio.com/items?itemName=pascal-lab.vide-ls) [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE) -Vide 是专为 Verilog/SystemVerilog 开发者打造的现代化编程开发环境，旨在让硬件设计像软件开发一样流畅顺手。Vide 提供了大量现代软件 IDE 标配，而硬件 IDE 缺失的代码分析功能，包括[定义跳转](https://vide.pascal-lab.net/user-guide/features/navigation/)、[代码注解](https://vide.pascal-lab.net/user-guide/features/annotations/)、[精准补全](https://vide.pascal-lab.net/user-guide/features/completion/)和[自动重构](https://vide.pascal-lab.net/user-guide/features/quick-fixes/)等。借助 Vide，硬件开发者可以更高效地理解、编写和维护 Verilog/SystemVerilog 代码。 +Vide 是专为 Verilog/SystemVerilog 开发者打造的现代化编程 IDE，旨在让硬件设计像软件开发一样流畅顺手。Vide 提供了大量现代软件 IDE 标配，而硬件 IDE 缺失的代码分析功能，包括[定义跳转](https://vide.pascal-lab.net/user-guide/features/navigation/)、[代码注解](https://vide.pascal-lab.net/user-guide/features/annotations/)、[精准补全](https://vide.pascal-lab.net/user-guide/features/completion/)和[自动重构](https://vide.pascal-lab.net/user-guide/features/quick-fixes/)等。借助 Vide，硬件开发者可以更高效地理解、编写和维护 Verilog/SystemVerilog 代码。 完整功能展示、安装说明、在线体验和用户手册请访问 [vide.pascal-lab.net](https://vide.pascal-lab.net/)。 diff --git a/docs/src/components/HomepageFeatureSection.astro b/docs/src/components/HomepageFeatureSection.astro index 50268df6..8cf59126 100644 --- a/docs/src/components/HomepageFeatureSection.astro +++ b/docs/src/components/HomepageFeatureSection.astro @@ -14,12 +14,12 @@ const locale = normalizeHomepageLocale(Astro.props.locale); { locale === 'en' ? ( <> - Make hardware design
feel as fluid as + Make hardware design
feel as fluid as developing software ) : ( <> - 让硬件设计
像开发软件一样丝滑顺手 + 让硬件设计
像开发软件一样丝滑顺手 ) } diff --git a/docs/src/content/docs/en/404.md b/docs/src/content/docs/en/404.md new file mode 100644 index 00000000..cd471606 --- /dev/null +++ b/docs/src/content/docs/en/404.md @@ -0,0 +1,9 @@ +--- +title: "404" +template: splash +editUrl: false +pagefind: false +hero: + tagline: Page not found. Check the URL or try using the search bar. + actions: [] +--- diff --git a/docs/src/content/docs/en/advanced-guide/parsing-and-analysis.md b/docs/src/content/docs/en/advanced-guide/parsing-and-analysis.md index 2f6e0322..82da06d2 100644 --- a/docs/src/content/docs/en/advanced-guide/parsing-and-analysis.md +++ b/docs/src/content/docs/en/advanced-guide/parsing-and-analysis.md @@ -13,22 +13,22 @@ Vide enters different working states depending on whether the workspace has `vid | State | What gets loaded | What it is for | | --- | --- | --- | -| No `vide.toml` | Verilog/SystemVerilog files in the workspace are scanned as best-effort indexes | Reading code first: basic go to definition, references, hover, and completion | +| No `vide.toml` | Verilog/SystemVerilog files in the workspace are scanned into a best-effort index | Initial code reading: basic definition jumps, references, hover, and completion | | `vide.toml` exists but omits `sources` | Best-effort indexing continues; if `include_dirs` is configured, those directories are loaded as include search paths | Transitional state; not recommended as a long-term setup | | `sources = []` | Workspace source scanning is explicitly disabled; if `include_dirs` is configured, only those include directories are loaded | Newly created templates, or workspaces where Vide should not guess the source layout | | `sources = ["rtl/**"]` | Project source files are loaded from `sources`, then combined with `include_dirs`, `defines`, `libraries`, and `top_modules` to build project analysis | Normal project configuration | A short way to remember it: -- Omitted `sources`: read the workspace for me, but do not treat the scan result as the real project. +- Omitted `sources`: scan the workspace for code reading, but do not treat the scan result as the configured project. - `sources = []`: do not scan source files automatically. - `sources = ["rtl/**"]`: these files are the current project sources. ## Best-Effort Indexing and Project Analysis -Best-effort indexing is for reading code. It tries to load RTL files in the workspace so go to definition, references, hover, completion, and instance-count lens can work early. It is not a real compile configuration, and it does not enable full project semantic diagnostics or project rename. +Best-effort indexing is for reading code. It tries to load RTL files in the workspace so definition jumps, references, hover, completion, and the instance-count lens can work early. It is not a real compile configuration, and it does not enable full project semantic diagnostics or project rename. -Project analysis comes from `vide.toml`. After `sources` points to real source files, Vide puts those files into the project view and uses `include_dirs`, `defines`, `libraries`, and `top_modules` for cross-file parsing, diagnostics, rename, and Qihe project analysis. +Project analysis comes from `vide.toml`. After `sources` points to actual source files, Vide adds those files to the project view and uses `include_dirs`, `defines`, `libraries`, and `top_modules` for cross-file parsing, diagnostics, rename, and Qihe project analysis. `libraries` are loaded as dependency workspaces and participate in the current project analysis. `exclude` removes generated files, simulation output, or black-box files from already loaded files. See [Project Configuration Reference](../../user-guide/project-configuration/#path-and-glob-rules-for-sources-and-exclude) for path and glob syntax. @@ -60,17 +60,17 @@ So it is normal to see basic diagnostics in an unconfigured workspace. For cross ## Navigation and Duplicate Modules -Go to definition, references, hover, completion, and instance-count lens prefer already loaded index information. Best-effort indexing lets those features work in unconfigured workspaces, but it can only make editor-level reading guesses. +Definition jumps, references, hover, completion, and the instance-count lens prefer already loaded index information. Best-effort indexing lets those features work in unconfigured workspaces, but it can only make editor-level guesses. In project analysis, duplicate module names are handled through the current project view. Vide does not treat directory names as implicit namespaces; if several duplicate module names are visible, the project should resolve that ambiguity through project configuration, library boundaries, or build scripts. -In best-effort indexing, if one instance can match several modules with the same name, Vide makes a nearest-candidate guess for reading features only: same file first, then deepest shared directory, then same scan root. The guess is used only when there is one best candidate; ties stay ambiguous. +In best-effort indexing, if one instance can match several modules with the same name, Vide makes a nearest-candidate guess for code-reading features only: same file first, then deepest shared directory, then same scan root. The guess is used only when there is one best candidate; ties stay ambiguous. This guess is not a SystemVerilog language rule. If there is one nearest candidate, Vide does not report a diagnostic. If no unique candidate exists, Vide reports an informational `ambiguous-module-instantiation` diagnostic. Configured projects still use stricter semantic rules; when third-party `slang` semantic diagnostics are enabled, Vide prefers slang's diagnostics. ## When Qihe Runs as a Project -Qihe integration reuses Vide's project configuration discovery result. If the working directory has a usable `vide.toml` and the compile plan contains real source files, Vide passes project files, `--top`, `-I`, and `-D` arguments. +Qihe integration reuses Vide's project configuration discovery result. If the working directory has a usable `vide.toml` and the compile plan contains actual source files, Vide passes project files, `--top`, `-I`, and `-D` arguments. If the current file only comes from best-effort indexing, or if the project configuration does not produce a usable compile plan, Vide falls back to single-file Qihe input. This avoids treating unconfigured scan results as a real project configuration. diff --git a/docs/src/content/docs/en/index.mdx b/docs/src/content/docs/en/index.mdx index be9f4b53..9ab0bbb4 100644 --- a/docs/src/content/docs/en/index.mdx +++ b/docs/src/content/docs/en/index.mdx @@ -1,14 +1,14 @@ --- title: Vide - Home -description: Vide - modern SystemVerilog development environment +description: Vide - a modern SystemVerilog development environment template: splash editUrl: false lastUpdated: false hero: title: | - VIDE : Modern SystemVerilog Coding IDE + VIDE: A Modern SystemVerilog IDE tagline: | - Bringing modern software development environment features into the hardware world. + Bringing modern software IDE capabilities to hardware design. actions: - text: Quick Start link: ./user-guide/ @@ -39,13 +39,3 @@ import HomepageHeroStyles from '../../../components/HomepageHeroStyles.astro'; - ---- - -
- PASCAL Research Group - PASCAL Research Group -
diff --git a/docs/src/content/docs/en/user-guide/features/completion.mdx b/docs/src/content/docs/en/user-guide/features/completion.mdx index 3ef7505f..0491263a 100644 --- a/docs/src/content/docs/en/user-guide/features/completion.mdx +++ b/docs/src/content/docs/en/user-guide/features/completion.mdx @@ -10,7 +10,7 @@ import { completionFiles } from '../../../../../examples/dailyUse'; ## What It Is -Completion inserts candidates at the current position. Vide combines syntax position and semantics to offer useful candidates and suppress irrelevant ones: target ports in instance port lists, target parameters in parameter lists, visible symbols in expressions, and directives or macro-related candidates in preprocessor positions. +Completion inserts candidates at the current position. Vide combines syntax context with RTL semantics to suggest useful candidates and suppress irrelevant ones: target ports in instance port lists, target parameters in parameter lists, visible symbols in expressions, and directives or macro-related candidates in preprocessor positions. Common trigger positions include instance `#(...)` and `(...)`, expressions, member access `.`, event controls `@(...)`, system tasks after `$`, preprocessor positions after `` ` ``, and integer literal base markers after `'`. diff --git a/docs/src/content/docs/en/user-guide/features/diagnostics.mdx b/docs/src/content/docs/en/user-guide/features/diagnostics.mdx index 6946aefc..e939cfa1 100644 --- a/docs/src/content/docs/en/user-guide/features/diagnostics.mdx +++ b/docs/src/content/docs/en/user-guide/features/diagnostics.mdx @@ -11,7 +11,7 @@ import { slangDiagnosticFiles } from '../../../../../examples/dailyUse'; ## What Diagnostics Are -Diagnostics are the errors, warnings, and hints that Vide asks the editor to show. They appear in the VS Code Problems panel, as editor underlines, and near the affected code, helping you find syntax errors, parse errors, and semantic issues found by project analysis. +Diagnostics are the errors, warnings, and hints that Vide reports to the editor. They appear in the VS Code Problems panel, as editor underlines, and near the affected code, helping you find syntax errors, parse errors, and semantic issues found by project analysis. Vide's regular syntax and semantic diagnostics mainly come from slang, and Vide converts them into editor markers and Problems entries. For deeper static analysis, use [Qihe Integration](../qihe/). diff --git a/docs/src/content/docs/en/user-guide/features/document-symbols.mdx b/docs/src/content/docs/en/user-guide/features/document-symbols.mdx index f33cf3c6..e6441841 100644 --- a/docs/src/content/docs/en/user-guide/features/document-symbols.mdx +++ b/docs/src/content/docs/en/user-guide/features/document-symbols.mdx @@ -21,7 +21,7 @@ Document symbols mainly come from the current file structure, so they work when ### With Complete Configuration -After `vide.toml` is configured, include files and macro branches are parsed from the project configuration, and the outline becomes closer to the structure seen in the real project. +After `vide.toml` is configured, include files and macro branches are parsed from the project configuration, and the outline more closely matches the structure seen in the actual project. ## Instance Count Lens diff --git a/docs/src/content/docs/en/user-guide/features/folding.mdx b/docs/src/content/docs/en/user-guide/features/folding.mdx index e4b2b333..1946ec36 100644 --- a/docs/src/content/docs/en/user-guide/features/folding.mdx +++ b/docs/src/content/docs/en/user-guide/features/folding.mdx @@ -10,7 +10,7 @@ import { inlayHintFiles } from '../../../../../examples/dailyUse'; Folding lets the editor collapse code by structure. Vide provides folding ranges for multi-line comments, regions, modules, port lists, declarations, generate/specify constructs, instances, continuous assignments, block statements, and ordinary statements. -During development, folding can skip over parts of the code and keep the editor view cleaner. +During development, folding lets you hide less relevant parts of the code and keep the editor view cleaner. ## Demo diff --git a/docs/src/content/docs/en/user-guide/features/hover.mdx b/docs/src/content/docs/en/user-guide/features/hover.mdx index 9a601457..66571df1 100644 --- a/docs/src/content/docs/en/user-guide/features/hover.mdx +++ b/docs/src/content/docs/en/user-guide/features/hover.mdx @@ -37,7 +37,7 @@ Hover is a lightweight explanation shown near the cursor. Place the mouse over a ### Without Complete Configuration -Declarations in the current file and number literals can be shown directly. Cross-file targets only show complete information when Vide has scanned the target file and can determine a unique target. +Modules, ports, and parameters declared in the current file, as well as number literals, can be shown directly. Cross-file targets only show complete information when Vide has scanned the target file and can determine a unique target. ### With Complete Configuration diff --git a/docs/src/content/docs/en/user-guide/features/index.mdx b/docs/src/content/docs/en/user-guide/features/index.mdx index f58e832f..03dd74d3 100644 --- a/docs/src/content/docs/en/user-guide/features/index.mdx +++ b/docs/src/content/docs/en/user-guide/features/index.mdx @@ -1,11 +1,11 @@ --- title: Features -description: Learn Vide go to definition, references, hover, completion, rename, syntax highlighting, semantic highlighting, annotations, document symbols, folding, refactoring, diagnostics, signature help, selection ranges, formatting, and Qihe integration. +description: Learn about Vide features including go to definition, references, hover, completion, rename, syntax highlighting, semantic highlighting, annotations, document symbols, folding, refactoring, diagnostics, signature help, selection ranges, formatting, and Qihe integration. --- import { CardGrid, LinkCard } from '@astrojs/starlight/components'; -This section introduces all features Vide provides in VS Code. Each feature has its own page. +This section introduces all of the features Vide provides in VS Code. Each feature has its own page. On each feature page, you will see: @@ -13,13 +13,13 @@ On each feature page, you will see: - a screenshot or interactive demo; - how to adjust behavior through `vide.toml` or VS Code Settings. The [Project Configuration](../project-configuration/#what-changes-after-configuration) page summarizes behavior before and after project configuration. -Before reading this section, read [Configure the First Project](../first-project/) first. Some deeper analysis features need a correct project configuration to work well. +Before reading this section, read [Configure the First Project](../first-project/) first. Some deeper analysis features require a well-formed project configuration. lightbulb menu, also called Code Actions. +Automatic refactoring handles repetitive, error-prone edits such as port connections, parameter assignments, and integer literal base conversion. In VS Code, you trigger these operations from the lightbulb menu, also called Code Actions. ## Demo @@ -55,6 +55,6 @@ Some refactorings for instances and integer literals are available in the curren ### With Complete Configuration -After `vide.toml` is configured, Vide finds target modules through `sources`, `include_dirs`, `defines`, and `libraries`. Filling ports, filling parameters, and converting connection styles use the real project structure. +After `vide.toml` is configured, Vide finds target modules through `sources`, `include_dirs`, `defines`, and `libraries`. Filling ports, filling parameters, and converting connection styles use the actual project structure. Diagnostic-driven quick fixes also require the matching diagnostic to be present in the current file. diff --git a/docs/src/content/docs/en/user-guide/features/references.mdx b/docs/src/content/docs/en/user-guide/features/references.mdx index 30e1a5a4..d466bad0 100644 --- a/docs/src/content/docs/en/user-guide/features/references.mdx +++ b/docs/src/content/docs/en/user-guide/features/references.mdx @@ -10,7 +10,7 @@ import { usageFiles } from '../../../../../examples/dailyUse'; ## What It Is -Find References answers “where is this symbol used?” In SystemVerilog projects, it is useful for tracing module instances, port connections, parameters, and signals, and for checking whether a connection relationship is complete. +Find References answers “where is this symbol used?” In RTL projects, it is useful for tracing module instances, port connections, parameters, and signals, and for checking whether connections are complete. Run VS Code's `Find All References` or `Peek References` on a symbol. Vide searches for its usage locations, deduplicates them, and shows them in the references view. diff --git a/docs/src/content/docs/en/user-guide/features/rename.mdx b/docs/src/content/docs/en/user-guide/features/rename.mdx index c7e13987..2e74d377 100644 --- a/docs/src/content/docs/en/user-guide/features/rename.mdx +++ b/docs/src/content/docs/en/user-guide/features/rename.mdx @@ -10,7 +10,7 @@ import { codeActionRenameFiles } from '../../../../../examples/dailyUse'; ## What It Is -Rename changes the declaration and references of the same SystemVerilog symbol together. It is safer than manual search-and-replace because Vide first decides which symbol is under the cursor, then generates a workspace edit, avoiding unrelated symbols with the same name. +Rename updates the declaration and references of the same SystemVerilog symbol together. It is safer than manual search-and-replace because Vide first resolves the symbol under the cursor, then generates a workspace edit that avoids unrelated symbols with the same name. ## Demo @@ -41,7 +41,7 @@ Without `vide.toml`, Vide can use workspace scan results for reference search, b ### With Complete Configuration -Add the source files that should participate in rename to `sources` or related `libraries`, then run `Vide: Reload Project Configuration`. Vide reloads the project scope, and rename updates declarations and references in those editable files. +With complete configuration, rename can work accurately. ## Boundaries diff --git a/docs/src/content/docs/en/user-guide/features/selection-range.mdx b/docs/src/content/docs/en/user-guide/features/selection-range.mdx index b3e38011..2cbf2aae 100644 --- a/docs/src/content/docs/en/user-guide/features/selection-range.mdx +++ b/docs/src/content/docs/en/user-guide/features/selection-range.mdx @@ -8,7 +8,7 @@ import { structureFiles } from '../../../../../examples/dailyUse'; ## What It Is -Selection range powers VS Code's `Expand Selection` and `Shrink Selection`. For example, when the cursor is on `choose_b`, repeated expansion can grow from `choose_b` to `.sel(choose_b)`, then to the whole instance connection, and then to the surrounding module. When copying, deleting, replacing, or wrapping SystemVerilog structures, you do not need to drag the mouse precisely to parentheses, commas, or `end`. +Selection range powers VS Code's `Expand Selection` and `Shrink Selection`. For example, when the cursor is on `choose_b`, repeated expansion can grow from `choose_b` to `.sel(choose_b)`, then to the whole instance connection, and then to the surrounding module. When copying, deleting, replacing, or wrapping SystemVerilog structures, you do not need to drag the mouse precisely over parentheses, commas, or `end`. There are two ways to run it: press `F1` and search `Expand Selection` or `Shrink Selection`; or use the default shortcuts, `Shift+Alt+Right` and `Shift+Alt+Left` on Windows/Linux, `Ctrl+Shift+Cmd+Right` and `Ctrl+Shift+Cmd+Left` on macOS. If another extension owns the shortcut, search `editor.action.smartSelect.expand` and `editor.action.smartSelect.shrink` in VS Code Keyboard Shortcuts to rebind them. @@ -35,4 +35,4 @@ Selection ranges mainly come from the current file's syntax structure, so they w ### With Complete Configuration -After `vide.toml` is configured, include files and macro branches are expanded from the project configuration, and selection levels from those structures match the real project. +After `vide.toml` is configured, include files and macro branches are expanded from the project configuration, and selection levels from those structures match the actual project. diff --git a/docs/src/content/docs/en/user-guide/features/semantic-highlighting.mdx b/docs/src/content/docs/en/user-guide/features/semantic-highlighting.mdx index 657be1c9..6ca64fc4 100644 --- a/docs/src/content/docs/en/user-guide/features/semantic-highlighting.mdx +++ b/docs/src/content/docs/en/user-guide/features/semantic-highlighting.mdx @@ -10,7 +10,7 @@ import { semanticTokenFiles } from '../../../../../examples/dailyUse'; ## What It Is -Syntax highlighting only knows whether a token looks like a keyword, number, or comment. Semantic highlighting further identifies what a name means in code. When reading code, you can more quickly distinguish clock/reset ports, input/output ports, module instance names, and `typedef` types. In the default display, input ports are bold (for example data_i), output ports are bold and underlined (for example data_o), and clock/reset ports use colors that differ from ordinary ports. +Syntax highlighting only knows whether a token looks like a keyword, number, or comment. Semantic highlighting goes further by identifying what a name means in the code. When reading code, you can distinguish clock/reset ports, input/output ports, module instance names, and `typedef` types more quickly. In the default display, input ports are bold (for example data_i), output ports are bold and underlined (for example data_o), and clock/reset ports use colors that differ from ordinary ports. ## Demo @@ -41,11 +41,13 @@ Ports, declarations, and types in the current file can receive basic semantic hi ### With Complete Configuration -After `vide.toml` is configured, semantic highlighting refreshes from the project structure. Port directions, clock/reset ports, instance names, and type names are identified with the real include files, macro definitions, and libraries. +After `vide.toml` is configured, semantic highlighting refreshes from the project structure. Port directions, clock/reset ports, instance names, and type names are identified using the actual include files, macro definitions, and libraries. ## Settings -If semantic highlighting does not look different, first confirm that the active VS Code theme supports semantic tokens. Vide provides two switches: +If semantic highlighting does not look different, first confirm that the active VS Code theme supports semantic tokens. You can also try another theme to check whether the markings take effect. + +Vide provides two switches: - `vide.semantic.tokens.port.clk.rst.enable`: controls clock/reset port tokens. - `vide.semantic.tokens.port.input.output.enable`: controls input/output direction tokens. diff --git a/docs/src/content/docs/en/user-guide/features/syntax-highlighting.mdx b/docs/src/content/docs/en/user-guide/features/syntax-highlighting.mdx index 77745f59..1c03a003 100644 --- a/docs/src/content/docs/en/user-guide/features/syntax-highlighting.mdx +++ b/docs/src/content/docs/en/user-guide/features/syntax-highlighting.mdx @@ -10,7 +10,7 @@ import { syntaxHighlightingFiles } from '../../../../../examples/dailyUse'; ## What It Is -Syntax highlighting colors keywords, comments, numbers, strings, and basic syntax structures. It does not need to understand the whole project first, so Verilog/SystemVerilog files get base coloring, comment recognition, bracket matching, and file icons as soon as they open. +Syntax highlighting colors keywords, comments, numbers, strings, and basic syntax structures. It does not need to understand the whole project first, so Verilog/SystemVerilog files get basic coloring, comment recognition, bracket matching, and file icons as soon as they open. ## Demo @@ -21,9 +21,9 @@ Syntax highlighting colors keywords, comments, numbers, strings, and basic synta files={syntaxHighlightingFiles} initialActiveFile="usage.v" title="Inspect Verilog syntax highlighting" - description="Load the example and open usage.v to inspect base coloring for module, input, wire, always, number literals, and comments." + description="Load the example and open usage.v to inspect basic coloring for module, input, wire, always, number literals, and comments." /> ## Project Configuration -None. Syntax highlighting does not depend on `vide.toml`. Once the Vide extension is enabled, Verilog/SystemVerilog files get basic syntax highlighting. +None. Syntax highlighting does not depend on `vide.toml`. Once the Vide extension is enabled, Verilog/SystemVerilog files get basic syntax highlighting automatically. diff --git a/docs/src/content/docs/en/user-guide/first-project.mdx b/docs/src/content/docs/en/user-guide/first-project.mdx index efba6403..28c56062 100644 --- a/docs/src/content/docs/en/user-guide/first-project.mdx +++ b/docs/src/content/docs/en/user-guide/first-project.mdx @@ -5,7 +5,7 @@ description: Write the first vide.toml for a small project. import { FileTree } from '@astrojs/starlight/components'; -Vide can provide syntax highlighting and basic editing after opening any Verilog/SystemVerilog project. To make cross-file navigation, completion, diagnostics, macro-branch selection, and Qihe argument derivation more accurate, add a project configuration file named `vide.toml` to the workspace root. +Vide provides syntax highlighting and basic editing as soon as you open a Verilog/SystemVerilog project. To make cross-file navigation, completion, diagnostics, macro-branch selection, and Qihe argument derivation more accurate, add a project configuration file named `vide.toml` to the workspace root. This page walks through a lightweight first configuration. For complete field details and boundary rules, see [Project Configuration Reference](../project-configuration/). @@ -31,7 +31,7 @@ sources = [] ``` :::note -- The default `sources = []` is an unfinished state: it tells Vide not to scan the whole workspace yet. Replace it with real paths such as `rtl/**`, and Vide will analyze the project according to that structure. +- The default `sources = []` is an unfinished state: it tells Vide not to scan the whole workspace yet. Replace it with actual paths such as `rtl/**`, and Vide will analyze the project according to that structure. - The leading `#:schema ...` line is a TOML comment. It can help editors identify the configuration format. ::: @@ -76,7 +76,7 @@ Always write paths with `/`, even on Windows. Use `rtl/**`, not `rtl\**`. All pa ## 3. A More Realistic Project Example -The `my-rtl` project above is intentionally small. Now use a real project, [darklife/darkriscv](https://github.com/darklife/darkriscv), as an example. The repository root contains `darkriscv.core`, which defines project information. A corresponding `vide.toml` can be: +The `my-rtl` project above is intentionally small. Next, look at a real project, [darklife/darkriscv](https://github.com/darklife/darkriscv). The repository root contains `darkriscv.core`, which defines project information. A corresponding `vide.toml` can be: ```toml #:schema https://vide.pascal-lab.net/schemas/v1/vide.schema.json @@ -138,8 +138,8 @@ After you save `vide.toml`, Vide reloads project configuration automatically by In practice there are three project states: -- No `vide.toml`: Vide scans the workspace for reading features, but does not create a project-level compilation profile. -- The empty default template: `sources = []` tells Vide not to scan the whole workspace yet, because the real source paths still need to be filled in. +- No `vide.toml`: Vide scans the workspace for code-reading features, but does not create a project-level compilation profile. +- The empty default template: `sources = []` tells Vide not to scan the whole workspace yet, because the actual source paths still need to be filled in. - A configured `vide.toml`: Vide understands the project through `sources`, `include_dirs`, `defines`, `libraries`, and related fields. For details, each [feature page](../features/) explains the behavior with and without project configuration. We also summarize the differences in [What Changes After Configuration](../project-configuration/#what-changes-after-configuration). diff --git a/docs/src/content/docs/en/user-guide/index.mdx b/docs/src/content/docs/en/user-guide/index.mdx index c4c8ce26..8e5781a7 100644 --- a/docs/src/content/docs/en/user-guide/index.mdx +++ b/docs/src/content/docs/en/user-guide/index.mdx @@ -5,9 +5,9 @@ description: Start using Vide from the online experience or VS Code installation import { CardGrid, LinkCard } from '@astrojs/starlight/components'; -Vide is a modern VS Code development environment for Verilog/SystemVerilog developers. It helps the editor understand module hierarchy, port connections, macro definitions, and include relationships in hardware projects. Work that used to depend on search, experience, and manual signal tracing becomes navigation, completion, checking, and refactoring directly in code. Whether you are taking over an unfamiliar design, completing instance ports, tracing a signal source, or using Qihe for deeper project analysis, Vide brings feedback into the editor workflow so RTL code is faster to read, modify, and maintain. +Vide is a modern development environment for Verilog/SystemVerilog developers, designed to make hardware design feel as fluid as software development. It brings more than a dozen capabilities that are standard in modern software IDEs but have long been missing from hardware workflows, including [Go to Definition](./features/navigation/), [Annotations](./features/annotations/), [Precise Completion](./features/completion/), and [Automatic Refactoring](./features/quick-fixes/). Most existing tools cover less than half of what Vide provides. With Vide, hardware developers can understand, write, and maintain Verilog/SystemVerilog code more efficiently. -If you only want to try the core features first, open the [Online Experience](./online-experience/) directly and use the core features without configuration. If you want to use Vide in your own project, start with [VS Code Installation](./vscode-installation/). +If you only want to get a feel for the core features, open the [Online Experience](./online-experience/) and try them without configuration. If you want to use Vide in your own project, start with [VS Code Installation](./vscode-installation/). ## Start Here @@ -15,38 +15,38 @@ If you only want to try the core features first, open the [Online Experience](./ ## Reading Guide -After trying Vide, continue in the order below. First-time users should read the tutorial and feature pages first; project configuration fields and VS Code settings are references to look up when needed. +After trying or installing Vide, continue in the order below. First-time users should start with [Configure the First Project](./first-project/) and [Features](./features/). Use [Project Configuration](./project-configuration/) and [VS Code Settings](./vscode-settings/) as references when needed. diff --git a/docs/src/content/docs/en/user-guide/online-experience.mdx b/docs/src/content/docs/en/user-guide/online-experience.mdx index 5b4f0203..fb73702f 100644 --- a/docs/src/content/docs/en/user-guide/online-experience.mdx +++ b/docs/src/content/docs/en/user-guide/online-experience.mdx @@ -1,6 +1,6 @@ --- title: Online Experience -description: Try Vide's core RTL IDE features in the browser without installing the local extension. +description: "Try Vide's core RTL IDE features in the browser without installing the local extension." --- import VideLab from '../../../../components/VideLab.astro'; @@ -11,17 +11,17 @@ import { structureFiles, } from '../../../../examples/dailyUse'; -We provide several small RTL projects that run directly in the browser. Without extra configuration, you can try symbol navigation, code insight, precise completion, and automatic refactoring. +The examples below are small RTL projects that run directly in the browser. Without extra configuration, you can try symbol navigation, code insight, precise completion, and automatic refactoring. When an example first loads, wait for the circle indicator in the upper-right corner of the editor to turn green. Then start from the selected code position. You can edit RTL, switch files, open the diagnostics panel, and use the reset button in the toolbar when you want to restore the initial state. ## Symbol Navigation -In traditional Verilog project development, finding where a variable is defined or used often means running a global Ctrl+F string search. That also pulls in similar names and same-named symbols from unrelated scopes, which quickly gets in the way. +In traditional Verilog projects, finding where a variable is defined or used often means running a global Ctrl+F string search. That search also returns similar names and identically named symbols from unrelated scopes, which quickly gets in the way. -In Vide, go to definition, find references, and document symbols help you move between modules, ports, and registers without leaving the current context, so you can trace RTL connections more directly. +In Vide, Go to Definition, Find References, and Document Symbols help you move between modules, ports, and registers without leaving the current context, so you can trace RTL connections more directly. -This example demonstrates go to definition and find references. +This example demonstrates Go to Definition and Find References. ### Steps @@ -69,9 +69,9 @@ This example demonstrates hover information for module signatures and instances, ## Precise Completion -Writing RTL without completion depends heavily on your memory of language syntax and project structure. If completion only does string matching, the candidate list is easily polluted by similar symbols and does not improve editing efficiency much. +Writing RTL without completion depends heavily on memory: language syntax, project structure, module ports, and signal names. If completion only does string matching, suggestions are easily cluttered with similar symbols and do little to speed up editing. -Vide's completion understands the current code context. It can provide more project-aware suggestions for instantiations, port connections, and other editing positions, and it can use snippets to provide structured completion. +Vide's completion understands the current code context. It provides project-aware suggestions for instantiations, port connections, and other editing positions, and uses snippets for structured edits. ### Steps @@ -93,11 +93,11 @@ Vide's completion understands the current code context. It can provide more proj ## Automatic Refactoring -Refactoring RTL often involves repetitive work, such as filling missing ports one by one during module instantiation, converting ordered port connections to named connections, or renaming symbols across declarations and uses. These repetitive operations are exactly the kind of detail a program can handle accurately. +Refactoring RTL often involves repetitive work: filling missing ports one by one during module instantiation, converting ordered port connections to named connections, or renaming symbols across declarations and uses. These mechanical edits are exactly the kind of detail the editor can handle accurately. -Vide provides automatic refactoring and rename support, so those mechanical details can be handled by the editor. +Vide provides automatic refactoring and rename support so the editor can handle those mechanical details for you. -This example demonstrates automatic completion for missing port connections and rename. +This example demonstrates missing-port completion and rename. ### Steps diff --git a/docs/src/content/docs/en/user-guide/project-configuration.mdx b/docs/src/content/docs/en/user-guide/project-configuration.mdx index a48d4212..4e40a34e 100644 --- a/docs/src/content/docs/en/user-guide/project-configuration.mdx +++ b/docs/src/content/docs/en/user-guide/project-configuration.mdx @@ -1,6 +1,6 @@ --- title: Project Configuration -description: Look up vide.toml fields, path globs, include directories, macro definitions, libraries, and exclusion rules. +description: Reference for vide.toml fields, path globs, include directories, macro definitions, libraries, and exclusion rules. --- import VideLab from "../../../../components/VideLab.astro"; @@ -94,7 +94,7 @@ endmodule }, ]; -This is a `vide.toml` project configuration reference. For first-time setup, first use [Configure the First Project](../first-project/) to write a working project configuration file. +This page is the `vide.toml` project configuration reference. For first-time setup, start with [Configure the First Project](../first-project/) to write a working project configuration file. ## Field Quick Reference @@ -149,9 +149,9 @@ In `include_dirs` and `libraries`, values are ordinary paths resolved relative t | Form | Result | | --- | --- | -| Omitted | Vide best-effort indexes the workspace for read features such as navigation, references, and hover, but does not treat it as a fully configured project. | +| Omitted | Vide creates a best-effort workspace index for code-reading features such as navigation, references, and hover, but does not treat it as a fully configured project. | | `sources = []` | Disables automatic workspace scanning. This is useful when you want to open the project safely and configure it later. | -| `sources = ["rtl/**"]` | Loads matching files with globs and puts them into project analysis. | +| `sources = ["rtl/**"]` | Loads matching files with globs and adds them to project analysis. | Common examples: @@ -215,10 +215,10 @@ exclude = ["build/**", "out/**", "sim/work/**", "**/*_bb.v"] | Area | Without a project configuration file | After `vide.toml` is configured | | --- | --- | --- | -| [Go to definition](../features/navigation/), [find references](../features/references/), and [hover](../features/hover/) | Scans the workspace and provides the jumps, references, and symbol information needed while reading code | Resolves targets through `sources`, `libraries`, include directories, and macro branches | -| [Completion](../features/completion/) and [signature help](../features/signature-help/) | Uses the current file and scanned files for candidates; shows port/parameter help once the target module is resolved | Uses target modules, include directories, and macro branches for candidates and current-position hints | -| [Rename](../features/rename/) and [quick fixes](../features/quick-fixes/) | Local code actions are available; project rename is disabled | Fills or converts ports and parameters across the project, and updates declarations, references, and connections | -| [Syntax highlighting](../features/syntax-highlighting/) and [semantic highlighting](../features/semantic-highlighting/) | Syntax highlighting is available, and the current file gets basic semantic markings | Uses project analysis to mark port directions, read/write locations, and macro branches | -| [Annotations](../features/annotations/), [document symbols](../features/document-symbols/), [folding](../features/folding/), and [selection range](../features/selection-range/) | The current file gets outline, folding, and selection ranges; annotations are shown after the target module is resolved | Shows ports, parameters, instance counts, outline, folding, and semantic selection ranges according to the project structure | +| [Go to Definition](../features/navigation/), [Find References](../features/references/), and [Hover](../features/hover/) | Scans the workspace and provides the jumps, references, and symbol information needed while reading code | Resolves actual targets through `sources`, `libraries`, include directories, and macro branches | +| [Completion](../features/completion/) and [Signature Help](../features/signature-help/) | Uses the current file and scanned files for candidates; shows port/parameter help once the target module is resolved | Uses target modules, include directories, and macro branches for candidates and position-aware hints | +| [Rename](../features/rename/) and [Automatic Refactoring](../features/quick-fixes/) | Local code actions are available; project rename is disabled | Fills or converts ports and parameters across the project, and updates declarations, references, and connections | +| [Syntax Highlighting](../features/syntax-highlighting/) and [Semantic Highlighting](../features/semantic-highlighting/) | Syntax highlighting is available, and the current file gets basic semantic markings | Uses project analysis to mark port directions, read/write locations, and macro branches | +| [Annotations](../features/annotations/), [Document Symbols](../features/document-symbols/), [Folding](../features/folding/), and [Selection Range](../features/selection-range/) | The current file gets outline, folding, and selection ranges; annotations are shown after the target module is resolved | Shows ports, parameters, instance counts, outline, folding, and semantic selection ranges according to the project structure | | [Diagnostics](../features/diagnostics/) | Open files get syntax and parse diagnostics; project-level semantic diagnostics are not created | Uses `sources`, `include_dirs`, and `defines` for cross-file semantic diagnostics | | [Qihe Integration](../features/qihe/) | Uses the current file as the analysis input | Derives compile arguments from `sources`, `top_modules`, `include_dirs`, and `defines` | diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 8f4b1a93..18447bed 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -1,6 +1,6 @@ --- title: Vide - 主页 -description: Vide - 现代 SystemVerilog 开发环境 +description: Vide - 现代 SystemVerilog 编程 IDE template: splash editUrl: false lastUpdated: false diff --git a/docs/src/content/docs/user-guide/index.mdx b/docs/src/content/docs/user-guide/index.mdx index d9c3e289..6c915f1a 100644 --- a/docs/src/content/docs/user-guide/index.mdx +++ b/docs/src/content/docs/user-guide/index.mdx @@ -5,7 +5,7 @@ description: 从在线体验或 VS Code 安装开始使用 Vide。 import { CardGrid, LinkCard } from '@astrojs/starlight/components'; -Vide 是专为 Verilog/SystemVerilog 开发者打造的现代化开发环境，旨在让硬件设计像软件开发一样流畅顺手。Vide 提供了十多项在现代软件开发环境中已成标配、却长期缺失于硬件开发环境的能力，包括但不限于[定义跳转](./features/navigation/)、[代码注解](./features/annotations/)、[精准补全](./features/completion/)和[自动重构](./features/quick-fixes/)等。而现有工具所能覆盖的功能，最多还不到 Vide 的一半。借助 Vide，硬件开发者可以更高效地理解、编写和维护 Verilog/SystemVerilog 代码。 +Vide 是专为 Verilog/SystemVerilog 开发者打造的现代化编程 IDE，旨在让硬件设计像软件开发一样流畅顺手。Vide 提供了十多项在现代软件开发环境中已成标配、却长期缺失于硬件开发环境的能力，包括但不限于[定义跳转](./features/navigation/)、[代码注解](./features/annotations/)、[精准补全](./features/completion/)和[自动重构](./features/quick-fixes/)等。而现有工具所能覆盖的功能，最多还不到 Vide 的一半。借助 Vide，硬件开发者可以更高效地理解、编写和维护 Verilog/SystemVerilog 代码。 ## 从这里开始 diff --git a/docs/src/content/docs/user-guide/online-experience.mdx b/docs/src/content/docs/user-guide/online-experience.mdx index 14f65ad6..94fe30af 100644 --- a/docs/src/content/docs/user-guide/online-experience.mdx +++ b/docs/src/content/docs/user-guide/online-experience.mdx @@ -17,7 +17,7 @@ import { ## 符号导航 -在以往的 Verilog 项目项目开发中，如果想要知道一个变量的定义或者使用位置，通常需要 Ctrl+F 来全局查找字符串，而这往往会把相似的变量名、不同作用域的重名符号带入搜索结果，大大影响了开发体验。 +在以往的 Verilog 项目开发中，如果想要知道一个变量的定义或者使用位置，通常需要 Ctrl+F 来全局查找字符串，而这往往会把相似的变量名、不同作用域的重名符号带入搜索结果，大大影响了开发体验。 而在 Vide 中，你可以使用定义跳转、引用搜索和符号大纲在模块、端口和寄存器之间快速定位，让开发者不用离开当前上下文也能追清 RTL 连接关系。 diff --git a/docs/src/data/homepage.ts b/docs/src/data/homepage.ts index a11e2f27..7d22dcc0 100644 --- a/docs/src/data/homepage.ts +++ b/docs/src/data/homepage.ts @@ -138,35 +138,35 @@ export const getHomepageFeatures = (localeInput?: string): HomepageFeature[] => layout: 'image-left', eyebrow: 'Navigation', title: 'Symbol Navigation', - description: `Use ${accent('Go to Definition')}, ${accent('Find References')}, and ${accent('Document Symbols')} in Vide to move quickly across modules, ports, and registers, so RTL connections can be traced without leaving the current context.

Writing RTL no longer has to start with Ctrl + F.`, + description: `Use ${accent('Go to Definition')}, ${accent('Find References')}, and ${accent('Document Symbols')} in Vide to move quickly across modules, ports, and registers, so you can trace RTL connections without leaving the current context.

Writing RTL no longer has to start with Ctrl + F.`, images: localizedImages('navigation', locale), }, { layout: 'image-right', eyebrow: 'Insight', title: 'Code Insight', - description: `Use Vide ${accent('Hover')} and ${accent('Inlay Hints')} to inspect modules, literals, and port connections in one editor window. Less window switching, more focus on the RTL design itself.`, + description: `Use Vide's ${accent('Hover')} and ${accent('Inlay Hints')} to inspect modules, literals, and port connections in one editor window, with less window switching and more focus on the RTL design itself.`, images: localizedImages('insight', locale), }, { layout: 'image-left', eyebrow: 'Completion', title: 'Precise Completion', - description: `Vide ${accent('Completion')} understands the current code context, suggests candidates that fit instantiations, port connections, and other editing positions, and provides structured edits through ${accent('Snippets')}.`, + description: `Vide's ${accent('Completion')} understands the current code context, suggests candidates suited to instantiations, port connections, and other editing positions, and provides structured edits with ${accent('Snippets')}.`, images: localizedImages('completion', locale), }, { layout: 'image-right', eyebrow: 'Refactoring', title: 'Automatic Refactoring', - description: `With ${accent('Automatic Refactoring')} and ${accent('Rename')}, Vide handles repetitive details such as port wiring, signal renames, and literal-base conversion, making RTL refactoring less mechanical.`, + description: `With ${accent('Automatic Refactoring')} and ${accent('Rename')}, Vide handles repetitive details such as port wiring, signal renames, and literal-base conversion, taking the busywork out of RTL refactoring.`, images: localizedImages('refactoring', locale), }, { layout: 'image-left', eyebrow: 'Diagnostics', title: 'Diagnostics', - description: `Vide reports code diagnostics as you edit, so errors surface earlier.

It can also combine with ${externalLink('https://qihe.pascal-lab.net', 'Qihe')} for deeper static analysis results directly inside the editor.`, + description: `Vide reports code diagnostics as you edit, so errors surface earlier.

It can also combine with ${externalLink('https://qihe.pascal-lab.net', 'Qihe')} for deeper static analysis results directly inside the editor, helping you find potential issues.`, images: localizedImages('diagnostics', locale), }, ]; @@ -300,7 +300,7 @@ const comparisonProductFeatures = (locale: HomepageLocale): ComparisonProduct[] folding: false, selectionRange: false, codeActions: - locale === 'en' ? 'Supports linter quick fixes and autoexpand' : '支持 linter 的 quickfix 和 autoexpand', + locale === 'en' ? 'Supports linter quick fixes and auto-expansion' : '支持 linter 的 quickfix 和 autoexpand', annotations: false, diagnostics: locale === 'en' ? 'Supports syntax errors and linter rules' : '支持语法错误和 linter 规则', },