Clarify diff report controls and README links
Document the text limit, JSON omission counters, and hierarchy options. Use absolute links for the documentation referenced by the README.
This commit is contained in:
parent
f474e9848c
commit
9d5fe27516
2 changed files with 28 additions and 17 deletions
22
README.md
22
README.md
|
|
@ -10,7 +10,7 @@ bindings and a C API.
|
||||||
|
|
||||||
Comparisons ignore timestamps and element order while preserving duplicates and
|
Comparisons ignore timestamps and element order while preserving duplicates and
|
||||||
other object details. They compare object fields and coordinates exactly; see the
|
other object details. They compare object fields and coordinates exactly; see the
|
||||||
[comparison rules](docs/comparison.md) for supported normalization and limits.
|
[comparison rules][comparison] for supported normalization and limits.
|
||||||
|
|
||||||
## Try the command-line tools
|
## Try the command-line tools
|
||||||
|
|
||||||
|
|
@ -24,8 +24,8 @@ pheon hierarchy chip.gds --format mermaid
|
||||||
```
|
```
|
||||||
|
|
||||||
`diff` returns 0 for equality, 1 for differences, and 2 for invalid or incomplete
|
`diff` returns 0 for equality, 1 for differences, and 2 for invalid or incomplete
|
||||||
comparisons. Start with the [CLI guide](docs/cli.md), then set up
|
comparisons. Start with the [CLI guide][cli], then set up
|
||||||
[Git integration](docs/git.md) if you review layouts in a repository.
|
[Git integration][git] if you review layouts in a repository.
|
||||||
|
|
||||||
## Read layouts in Python
|
## Read layouts in Python
|
||||||
|
|
||||||
|
|
@ -45,13 +45,21 @@ print(layout.field("lib_name")[0].as_py())
|
||||||
```
|
```
|
||||||
|
|
||||||
Source installation needs Rust; prebuilt Python wheels bundle the native library.
|
Source installation needs Rust; prebuilt Python wheels bundle the native library.
|
||||||
The [Python guide](docs/python.md) covers installation, selected reads, and integer
|
The [Python guide][python] covers installation, selected reads, and integer
|
||||||
packing. The [Arrow reference](docs/arrow-schema.md) describes the returned data.
|
packing. The [Arrow reference][arrow] describes the returned data.
|
||||||
|
|
||||||
## Learn more
|
## Learn more
|
||||||
|
|
||||||
Browse the [documentation](docs/index.md) for layer names, native integration,
|
Browse the [documentation][docs] for layer names, native integration,
|
||||||
JSON reports, development, and releases. For writing, Pheon provides low-level
|
JSON reports, development, and releases. For writing, Pheon provides low-level
|
||||||
GDSII record helpers in Rust.
|
GDSII record helpers in Rust.
|
||||||
|
|
||||||
Licensed under [GPL-3.0-only](LICENSE.md).
|
Licensed under [GPL-3.0-only][license].
|
||||||
|
|
||||||
|
[arrow]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/arrow-schema.md
|
||||||
|
[cli]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/cli.md
|
||||||
|
[comparison]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/comparison.md
|
||||||
|
[docs]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/index.md
|
||||||
|
[git]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/git.md
|
||||||
|
[license]: https://mpxd.net/code/jan/pheon/src/branch/master/LICENSE.md
|
||||||
|
[python]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/python.md
|
||||||
|
|
|
||||||
23
docs/cli.md
23
docs/cli.md
|
|
@ -99,18 +99,21 @@ pheon diff before.gds after.gds --hierarchy mermaid --depth 4
|
||||||
|
|
||||||
`--show-cell` and `--show-layer` filter displayed changes without changing the
|
`--show-cell` and `--show-layer` filter displayed changes without changing the
|
||||||
comparison, totals, or exit status. A layer display filter hides references
|
comparison, totals, or exit status. A layer display filter hides references
|
||||||
without a numeric layer. `--max-changes N` limits displayed object occurrences.
|
without a numeric layer. `--max-changes N` limits displayed object occurrences
|
||||||
Text shows a replacement only when both objects fit within the limit.
|
after filtering. Text defaults to 100 occurrences and shows a replacement only
|
||||||
A single omission line lists changes hidden by filters or the limit. JSON
|
when both objects fit within the limit. A single omission line lists changes
|
||||||
includes all changed objects unless the limit is explicit.
|
hidden by filters or the limit. JSON has no default object limit and reports
|
||||||
|
omissions from both display filters and any explicit limit in `report_selection`.
|
||||||
|
See the [JSON reference](diff-reports.md) for the selection counters.
|
||||||
|
|
||||||
The diff hierarchy shows directly changed cells, affected ancestors, and targets
|
The diff hierarchy shows directly changed cells, affected ancestors, and targets
|
||||||
of modified references. It includes references from both revisions so removed
|
of modified references. It includes references from both revisions so removed
|
||||||
branches remain visible. Counts represent direct placements;
|
branches remain visible. Counts represent direct placements, with symbolic
|
||||||
arrays remain symbolic. ASCII omits the section when there are no cell changes
|
counts for arrays. ASCII omits the section when there are no cell changes and
|
||||||
and marks reference changes whose placement count stays the same.
|
marks reference changes whose placement count stays the same. Use `--depth`
|
||||||
`--depth` limits text diagrams. For a complete graph in
|
with text output.
|
||||||
JSON, use `--format json --hierarchy graph`; text depth and display filters do
|
For the complete graph within the comparison scope, use
|
||||||
not trim that graph.
|
`--format json --hierarchy graph` without `--depth`. Display filters leave the
|
||||||
|
graph intact.
|
||||||
|
|
||||||
Next: configure [Git integration](git.md) or add [layer names](layer-names.md).
|
Next: configure [Git integration](git.md) or add [layer names](layer-names.md).
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue