ENH/DOC: docstrings + start of API docs

klauer commented 9 months ago

(This is part of a larger branch which got to be unmanageably large - breaking it up into separate PRs. This is the largest of them!)

Add Sphinx API docs, initially focused on blark.transform dataclasses
- Dataclass documentation will show the associated Lark grammar rules
Add docstrings to all dataclasses that correspond to grammar rules
- Add some examples where helpful
Changes assignment rules to use named tokens for better syntax highlighting (related to #88, really - see message above about this being from a larger branch)
- This may be an unexpected change if you're using the grammar without blark's dataclass tooling. (If such changes are problematic to you, feel free to reach out and we can chat...)
CodeSummary.from_parse_results can now take just a single parse result, for convenience
Some additional fixes for blark.summary and (non-smoke!) test coverage
Comment pre-parsing will now include positional metadata (such that you can say code[start:end] is where this single/multi-line comment came from). This is actually important for #88 again but is more effort to separate than I want to bother with.

API doc example

For S=, we have blark.transform.SetStatement. This renders in sphinx as:

TODO

[ ] Add CI job to build and deploy documentation

Documentation won't be "done" once the above is complete and this is merged, for what it's worth. blark is a work-in-progress and this is just the start of this specific effort.

codecov-commenter commented 9 months ago

Codecov Report

Merging #89 (9dd8403) into master (d204cbb) will increase coverage by 0.8%. The diff coverage is 89.7%.

@@           Coverage Diff            @@
##           master     #89     +/-   ##
========================================
+ Coverage    80.5%   81.3%   +0.8%     
========================================
  Files          26      26             
  Lines        5570    5743    +173     
========================================
+ Hits         4484    4671    +187     
+ Misses       1086    1072     -14

Files	Coverage Δ
blark/tests/test_summary.py	`98.7% <100.0%> (+0.4%)`	:arrow_up:
blark/tests/test_util.py	`100.0% <100.0%> (ø)`
blark/parse.py	`78.6% <70.0%> (-0.5%)`	:arrow_down:
blark/util.py	`84.7% <92.0%> (+0.9%)`	:arrow_up:
blark/summary.py	`79.8% <77.7%> (+4.6%)`	:arrow_up:
blark/transform.py	`98.3% <89.9%> (-0.7%)`	:arrow_down:

... and 1 file with indirect coverage changes

klauer commented 9 months ago

Actually, I'll add the CI job for documentation building/deployment in another PR ... merging for now

klauer / blark