docs: Introduce the xDSL book #2465
Conversation
|
I think after rewriting it would be nice to have a chapter about standard dialects, explaining their role and rationale, akin to how CIRCT does it. |
docs/book/src/SUMMARY.md
Outdated
| - [Dialects](ir/dialects.md) | ||
| - [Attributes](ir/attributes.md) | ||
| - [Regions](ir/regions.md) | ||
| - [Verifiers](ir/verifiers.md) |
There was a problem hiding this comment.
| - [Dialects](ir/dialects.md) | |
| - [Attributes](ir/attributes.md) | |
| - [Regions](ir/regions.md) | |
| - [Verifiers](ir/verifiers.md) | |
| - [Attributes](ir/attributes.md) | |
| - [Operations](ir/operations.md) | |
| - [Regions](ir/regions.md) | |
| - [Verifiers](ir/verifiers.md) | |
| - [Dialects](ir/dialects.md) |
There was a problem hiding this comment.
Yes. I feel like traits could be introduced later, after rewriting, in a re-visit to introduce more complex concepts like traits/interfaces. But maybe there is not enough material to do this.
There was a problem hiding this comment.
Custom syntax also somewhere late
| for f in docs/book/**/*.py; do | ||
| echo "Running book code: '$f'"; | ||
| python "$f"; | ||
| done |
There was a problem hiding this comment.
can you please add this to make tests? this script should probably be running those tests also, but that's for another PR. Ideally test book.
There was a problem hiding this comment.
I am not sure if this script is the best way to do this in the first place. With your Python build system experience, would you do it differently?
There was a problem hiding this comment.
Actually why this format and not the way we have it in Toy, as just an extra project with source files and pytest tests?
There was a problem hiding this comment.
Could you detail a bit more? The files that will be added will most likely not have the usual "list of functions" format used with pytest.
There was a problem hiding this comment.
This is partially why I suggested moving the Toy tutorial. Even though it's not what we want to have in the book in the long run, it contains realistic snippets of code, and would immediately surface missing functionality.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2465 +/- ##
=======================================
Coverage 89.77% 89.77%
=======================================
Files 350 350
Lines 42747 42747
Branches 6353 6353
=======================================
Hits 38376 38376
Misses 3434 3434
Partials 937 937 ☔ View full report in Codecov by Sentry. |
|
I'm sorry, I intended to delete my local branch, and it deleted both the local and remote branch for some reason |
|
I'm happy to reopen the PR, if you'd like me to |
This PR introduces a mdbook that should be used as an entry point for MLIR/xDSL newcomers. This is only an infrastructure setup, actual book content should be discussed later. For now, an example structure has been added for demonstration purposes.
This set up allows embedding Python code within the book. The CI has been updated to verify this Python code will run without error. How to use the infrastructure is detailed in the added book README.
Here is a screenshot of one of the pages, with dark theme enabled: