documentation: automatically generate documentation from all .py files in xDSL #3758
Conversation
superlopuh
requested review from
compor,
alexarice,
math-fehr and
EdmundGoodman
There was a problem hiding this comment.
I'm not sure that this is actually how we want to print this
xdsl/dialects/riscv_snitch.py
Outdated
There was a problem hiding this comment.
Without code blocks, the [] are treated as md references, which raises errors during the build, and looks ugly on the page.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #3758 +/- ##
=======================================
Coverage 91.25% 91.25%
=======================================
Files 461 461
Lines 57479 57479
Branches 5543 5543
=======================================
Hits 52455 52455
Misses 3602 3602
Partials 1422 1422 ☔ View full report in Codecov by Sentry. |
| """ | ||
| number of chunks into which communication and computation should be split. | ||
| Effectively, the number of times `csl_stencil.apply.receive_chunk` will be | ||
| executed and the tensor sizes it handles. Higher values may increase compute | ||
| overhead but reduce size of communication buffers when lowered. | ||
| """ |
|
Wdym by "if we commit these files"? You don't mean the generated documentation, right? |
|
Yep there's a way to actually do it for each pull request and with a diff view: |
Great! Maybe that's the way to go? |
|
Definitely, I just need to move our jupyter notebooks over first as they currently deploy with github pages |
There was a problem hiding this comment.
Looks good to me!
Is the plan to deply to GitHub pages with the https://xdsl.dev website or readthedocs.io? The latter might break some URLs but might provide some other features for free?
Also something to consider is versioning the docs (at least after the first major semantic versioned release, but don't want to have to rebuild doc infrastructure then) can be quite valuable, which you can do with https://github.com/jimporter/mike for mkdocs-material on GitHub pages, but I am not sure how this would play with readthedocs.io?
mkdocs.yml
Outdated
| @@ -5,9 +5,27 @@ theme: | |||
|
|
|||
| plugins: | |||
| - search | |||
| - gen-files: | |||
| scripts: | |||
| - scripts/gen_ref_pages.py | |||
| - mkdocstrings | |||
There was a problem hiding this comment.
You can get a bit more out of this extension with some more settings. In the past I've used something like this:
- mkdocstrings:
handlers:
python:
options:
docstring_style: google
members_order: source
show_root_heading: true
show_root_full_path: false
show_signature_annotations: trueBut it might be a bit verbose for a very large codebase
superlopuh
force-pushed
the
sasha/docs/autogen
branch
from
96387ea to
5987c61
Compare
superlopuh
force-pushed
the
sasha/docs/autogen
branch
from
5987c61 to
fbcdb54
Compare
superlopuh
changed the title
…s in xDSL (#3758) Excludes: - `__main__.py` files - `_`-prefixed files - `xdsl/irdl/error.py` as it contains a function called `error` which confuses the doc mechanism for some reason - `xdsl/ir/*.py` as we've already got curated docs for these files Still needs a bit of cleanup and to merge the code changes separately. The big question for this PR is whether we want to commit these files and, if not, how do we review them?
…s in xDSL (xdslproject#3758) Excludes: - `__main__.py` files - `_`-prefixed files - `xdsl/irdl/error.py` as it contains a function called `error` which confuses the doc mechanism for some reason - `xdsl/ir/*.py` as we've already got curated docs for these files Still needs a bit of cleanup and to merge the code changes separately. The big question for this PR is whether we want to commit these files and, if not, how do we review them?
Excludes:
__main__.pyfiles_-prefixed filesxdsl/irdl/error.pyas it contains a function callederrorwhich confuses the doc mechanism for some reasonxdsl/ir/*.pyas we've already got curated docs for these filesStill needs a bit of cleanup and to merge the code changes separately.
The big question for this PR is whether we want to commit these files and, if not, how do we review them?