Closed shaedrich closed 4 months ago
Name | Link |
---|---|
Latest commit | f3c555243bcf24ea093142427588539226d95b47 |
Latest deploy log | https://app.netlify.com/sites/pony-tutorial/deploys/665f5b08f477050008365761 |
Deploy Preview | https://deploy-preview-545--pony-tutorial.netlify.app |
Preview on mobile | Toggle QR Code...Use your smartphone camera to open QR code link. |
To edit notification comments on pull requests, go to your Netlify site configuration.
fyi: There's currently an issue with auto dedention (https://github.com/facelessuser/pymdown-extensions/issues/1945) when using the block format and splitting a snippet into multiple pieces: https://github.com/facelessuser/pymdown-extensions/issues/2385
env.out.print("the comment")
in some cases, except
Main::create()
, where we have direct access to env
Foo
with the methods and variables and Bar
where Foo
is called
Bar
could be turned into Main
, which would be beneficial, because
Main
is needed anywayMain::create()
, we have direct access to env
None
Main::create()
...
)
// ...
)When examples are taken from stdlib, wouldn't it make sense to use URL snippets (or, assuming, all the sites are on the same server, maybe another path in mkdocs.yml markdown_extensions.pymdownx.snippets.base_path
would suffice) from https://github.com/ponylang/ponyc (example)?
fyi: The deploy preview only fails due to flaky connectivity.
Error from the last build log:
12:41:17 PM: ERROR - Error reading page 'c-ffi/calling-c.md': Snippet at path 'https://raw.githubusercontent.com/ponylang/ponyc/main/packages/builtin/float.pony' could not be found
This is an impressive amount of work. Thank you @shaedrich.
This is an impressive amount of work. Thank you @shaedrich.
@SeanTAllen Thanks a lot 😊
Error from the last build log:
12:41:17 PM: ERROR - Error reading page 'c-ffi/calling-c.md': Snippet at path 'https://raw.githubusercontent.com/ponylang/ponyc/main/packages/builtin/float.pony' could not be found
@SeanTAllen This is fixed by the revert requested by @jemc
Is this PR meant to be in a ready for review/merge state?
I ask because it's not marked as a draft, but there are unchecked checkboxes in the PR description.
It isn't clear to me whether we should be giving this a final review yet.
@jemc Please read the PR description as well as my previous comments. If none of them require any action in your opinion, the PR is indeed ready to be merged. The unchecked checkboxes mean, these code snippets are not runnable and might not have been changed in this PR, but this doesn't necessarily need to be a problem.
Well, what use is it to have an example being run by the playground and it just doesn't fail? When I use the playground, I want it to output something. Otherwise the tutorial can simply talk about code and I have to accept that it does what the text says.
I think what you've done here does add value to the kind of user who wants to click through on these code samples and run them in the playground. I don't think that will be a high volume of users, but I agree your work here adds value for them (which is why I marked it as approved).
However, I don't want to create new requirements for tutorial content that raise the bar for what needs to be created there. That's why I want to ensure that the future mechanism which tests these samples can run at least some samples in a mode where we're only verifying that they compile (which should be part of the minimum bar for tutorial content contribution - that the code samples compile if expected to compile, or fail with specified errors if they are expected to fail to compile).
In short, we have to balance the needs of both the tutorial reader and the tutorial contributor. The more friction we add to the tutorial contribution process, the harder it becomes to get volunteers to do the work.
fail with specified errors
This one is a bit puzzling to me. So, in essence, you want failure to be more defined than success? That doesn't make sense to me. You don't want to test beyond compilation, okay, but why bother with error codes/messages? Why not just make a *.txt
file with one exception per line that isn't tested and be done with it? Low maintenance, exactly what you want.
I'm trying to engage in a good faith exchange of opinions and arguments/reasoning here, but it becomes hard to justify continuing that engagement when comments like this appear to be strawmanning me with an apparent petulant tone.
Why not just make a *.txt file with one exception per line that isn't tested and be done with it? Low maintenance, exactly what you want.
We've talked at length in this PR and elsewhere about "what I want" and that isn't it.
So, no.
I'm trying to engage in a good faith exchange of opinions and arguments/reasoning here, but it becomes hard to justify continuing that engagement when comments like this appear to be strawmanning me with an apparent petulant tone.
It's right when they say, the internet doesn't do a good point of getting one's point across in terms of the message's notions. If you indeed read my message in good faith, there is nothing that would objectively hint at a petulant tone.
What I'm trying to do is merely to understand your position, which I'm struggling to do, as I tried to convey in my last message. If you're willing to make this clear, I'm interested in your explanation. If you don't want to and still take this personally, there's not much I can do.
In more than one comment, I explicitly stated that I hope, I'm not speaking out of line by just stating my different opinion on the matter at hand because I thought, this perspective would be beneficial for the project.
I just listened to your sync recording, and I think, I understand one of your concerns better, concerning using stderr to determine if the code snippet run failed accordingly. Yeah, error messages could change, so something else should be used. Meaning, the problem is not with wanting to determine the reason of the run failing but the way of achieving that. However, this is complicated in itself, but might become easier if ponylang/rfcs#76 got implemented.
See #340
As per https://github.com/ponylang/pony-tutorial/pull/542#issuecomment-2113695598
Stats
Files
Getting Started
--8<-- "hello-world-main.pony
→ runnable--8<-- "hello-world-main.pony
→ runnable--8<-- "hello-world-main.pony::1
→ not runnable--8<-- "hello-world-main.pony:2:2
→ not runnable--8<-- "hello-world-main.pony:3:3
→ not runnableTypes
--8<-- "classes-swap-values-sugar.pony
:6:6
"
→ runnable--8<-- "classes-swap-values.pony
:6:8
"
→ runnableclasses-wombat-constructor-invocation.pony(see classes-wombat.pony)--8<-- "classes-wombat.pony
:8:18
"
→ runnable--8<-- "classes-wombat.pony:
1:1
9:9
"
→ not runnable--8<-- "classes-wombat.pony:
1:3
9:11
"
→ not runnable--8<-- "classes-wombat
-constructor-invocation
.pony:
3:4
"
→ runnableclasses-zero-argument-constructors-invocation.pony(see classes-zero-argument-constructors.pony)--8<-- "classes-zero-argument-constructors.pony
:9:16
"
→ runnable--8<-- "classes-zero-argument-constructors
-invocation
.pony
:5:17
"
→ runnable--8<-- "primitives-doors.pony"
→ runnable--8<-- "traits-and-interfaces-marker-methods.pony
:1:1
"
→ not runnable--8<-- "traits-and-interfaces-marker-methods.pony"
→ not runnable--8<-- "traits-and-interfaces-multiple-traits.pony
:6:12
"
→ runnable--8<-- "traits-and-interfaces-nested-traits.pony
:6:12
"
→ runnable--8<-- "traits-and-interfaces-nominal-and-structural-subtyping.pony
:8:14
"
→ runnable--8<-- "traits-and-interfaces-nominal-subtyping-in-pony
:6:7
"
→ runnabletraits-and-interfaces-open-world-interface.pony(see traits-and-interfaces-marker-methods.pony)--8<-- "raits-and-interfaces-open-world-typing.pony
:6:9
"
→ runnabletraits-and-interfaces-structural-subtyping.pony:18:19 --8<-- → runnable
--8<-- "traits-and-interfaces-trait.pony
:20:36
"
→ runnable--8<-- "type-aliases-complex-types-interface.pony
:6:15
"` → runnable--8<-- "type-aliases-complex-types-trait.pony
:6:15
"` → runnable--8<-- "type-aliases-enumerations-iteration.pony
:15:19
"
→ runnable--8<-- "type-aliases-enumerations-iteration.pony"
--8<--
type-aliases-enumerations-apply.pony:21:23
type-aliases-enumerations-apply.pony:11:13
--8<--
type-aliases-enumerations-iteration.pony(see type-aliases-enumerations-apply.pony)Expressions
--8<-- "literals-array-literals.pony
:3:7
"` → runnable--8<-- "literals-character-literals.pony
:3:5
"` → runnable--8<-- "literals-number-types.pony
:3:5
"` → runnable--8<-- "literals-string-literals-encoding.pony
:3:3
"`--8<-- literals-string-literals-instances.pony:3:6 literals-string-literals-instances.pony:10:10 --8<--
--8<-- "variables-fields-constructor-assignment.pony
:6:12
"` → runnable--8<-- "variables-fields-definition-assignment.pony
:6:8
"` → runnable--8<-- "variables-fields-let-reassignment.pony
:5:17
"` → runnable--8<-- "variables-let-reassignment.pony
:3:5
"` → runnable--8<-- "variables-scope.pony
:6:11
"` → runnable--8<-- "variables-var-vs-let.pony
:3:6
"` → runnable--8<-- "operators-add.pony"--8<-- operators-add.pony:8:19 operators-add.pony:23:29 --8<-- → runnable--8<-- " operators-precedence-unary-operator-with-parentheses.pony
:3:3
"` → runnable--8<-- "operators-precedence-without-parentheses.pony
:3:3
"` → runnable--8<-- "arithmetic-partial-and-check-arithmetic.pony"--8<-- arithmetic-partial-and-check-arithmetic.pony:7:14 arithmetic-partial-and-check-arithmetic.pony:16:20 arithmetic-partial-and-check-arithmetic.pony:22:22 arithmetic-partial-and-check-arithmetic.pony:24:26 --8<-- → runnable--8<-- "control-structures-conditionals-expression-implicit-none.pony
:4:7
"` → runnable--8<-- "control-structures-conditionals-expression-union-type.pony
:4:9
"` → runnable--8<-- "control-structures-conditionals-expressions.pony
:5:5
"` → runnable--8<-- "control-structures-conditionals-if-else.pony
:5:9
"` → runnable--8<-- "control-structures-conditionals-if-elseif-else.pony
:5:11
"` → runnable--8<-- "control-structures-conditionals-if.pony
:5:7
"` → runnable--8<-- "control-structures-conditionals-nested-if-else.pony
:5:13
"` → runnable--8<-- "control-structures-loops-for-while-comparison.pony
:4:8
"` → runnable--8<-- "control-structures-loops-for.pony
:3:5
"` → runnable--8<-- "control-structures-loops-while-break-else.pony
:10:19
"` → runnable--8<-- "control-structures-loops-while.pony
:3:8
"` → runnable--8<-- "match-captures.pony
:6:13
"` → runnable--8<-- "match-guards.pony
:6:15
"` → runnable--8<-- "match-tuples-ignore-elements.pony
:5:13
"` → runnable--8<-- "match-tuples.pony
:5:13
"` → runnable--8<-- "match-type-and-value.pony
:6:14
"` → runnable--8<-- "match-values.pony
:6:14
"` → runnable--8<-- "as-operator-match-statement-comparison.pony
:11:23
"` → runnable--8<-- "as-operator-match-statement-without-try.pony
:11:19
"` → runnable--8<-- "as-operator-more-specific-interface-with-reference-capability.pony
:11:18
"` → runnable--8<-- "as-operator-unrelated-type.pony
:1:10
"` → runnable--8<-- "methods-constructors.pony
:6:13
"` → runnable--8<-- "methods-functions.pony
:6:11
"` → runnable--8<-- "errors-partial-functions.pony
:16:22
"` → runnable--8<-- "errors-try-else.pony
:9:15
"` → runnable--8<-- "errors-try-then.pony
:9:17
"` → runnable--8<-- "update-additional-parameters.pony
:18:18
"` → runnable--8<-- "sugar-update-explicit.pony
:18:18
"` → runnable--8<-- "sugar-update-implicit.pony
:18:18
"` → runnable--8<-- "object-literals-actor-literal.pony
:4:6
"` → runnable--8<-- "object-literals-fields-assignment.pony
:1:8
"` → runnable--8<-- "object-literals-fields-assignment.pony
:1:9
"` → runnable--8<-- "object-literals-lambda-as-explicit-object-literal.pony
:4:6
"` → runnable--8<-- "object-literals-lambda-captur-eand-rename-values.pony
:6:7
"` → runnable--8<-- "object-literals-lambda-capture-values.pony
:5:10
"` → runnable--8<-- "object-literals-lambda-with-reference-capability-as-explicit-object-literal.pony
:4:6
"` → runnable--8<-- "object-literals-lambda-as-with-reference-capability.pony
:4:4
"` → runnable--8<-- "object-literals-lambda.pony
:5:5
"` → runnable--8<-- "object-literals-object-literal-with-interface.pony
:6:9
"` → runnable--8<-- "object-literals-object-literal.pony
:4:6
"` → runnable--8<-- "object-literals-fields-assignment.pony
:1:9
"` → runnableReference capabilities
--8<-- "consume-and-destructive-read-consuming-a-variable.pony:
1
5
:
2
6
"
→ runnable, prints nothing--8<-- "consume-and-destructive-read-consuming-a-variable
-failure
.pony
:5:7
"
→ runnable, fails with--8<-- "recovering-capabilities-string-append.pony
:3:4
"
--8<-- "recovering-capabilities-with-explicit-reference-capability.pony
:5:5
"
→ runnable--8<-- "aliasing-iso-to-tag.pony
:5:6
"
→ runnable--8<-- "aliasing-multiple-references-to-an-iso-object.pony
:5:6
"
→ runnable--8<-- "aliasing-trn-to-box.pony
:5:6
"
→ runnableObject capabilities
--8<-- "derived-authority-delegating-and-restricting-authority.pony"
→ runnable--8<-- "derived-authority-delegating-and-restricting-authority.pony:18:18"
→ not runnable--8<-- "derived-authority-restrict-then-delegate-your-authority.pony
:16:22
"
Generics
ref
missing, could then just be a snippet ofgenerics-and-reference-capabilities-foo-iso
--8<-- "generics-foo-string.pony
:1:9
"
→ runnablegenerics-generic-class-initialization.pony(see generics-foo-with-any-val.pony)--8<-- "generics-type-parameter-defaults<del>-definition</del>.pony
:1:9
"
--8<-- "generics-type-parameter-defaults<del>-initialization</del>.pony
:13:15
"
generics-type-parameter-defaults-initialization.pony(see generics-type-parameter-defaults-definition.pony)Packages
time.pony
Testing
ponycheck-ponytest.pony(seeponycheck-usage.pony
)--8<-- "ponycheck-usage.pony
:2:12
"
→ runnable--8<-- ponycheck-usage.pony:1:3 ponycheck-usage.pony:14:19 --8<-- → runnable--8<-- "ponycheck-ponytest.pony"
C-FFI
--8<-- "ac-abi-jump-consistent-hashing.pony
:5:18
"
→ runnable--8<-- "calling-c-from-c-struct.pony
:1:5
"
--8<-- "calling-c-ioctl-struct.pony"--8<-- calling-c-ioctl-struct.pony:1:8 calling-c-ioctl-struct.pony:11:15 --8<-- → runnable--8<-- "calling-c-variadic-c-functions.pony"--8<-- calling-c-variadic-c-functions.pony:1:2 calling-c-variadic-c-functions.pony:10:12 --8<-- → runnable--8<-- "calling-c-writev-struct.pony"--8<-- calling-c-writev-struct.pony:1:12 calling-c-writev-struct.pony:15:19 --8<-- → runnable--8<-- "calling-c-writev-tuple.pony"--8<-- calling-c-writev-tuple.pony:1:2 calling-c-writev-tuple.pony:5:7 --8<-- → runnableGotchas
--8<-- "divide-by-zero.pony
:4:4"
"
→ runnable--8<-- "divide-by-zero.pony
:3:3"
"
→ runnable--8<-- "recursion.pony
:7:19"
"
→ runnableAppendices
--8<-- "appendices-annotations-empty-with-nosupertype-annotation.pony
:1:7
"
→ runnable--8<-- "appendices-annotations-likely-and-unlikely-annotations.pony"--8<-- appendices-annotations-likely-and-unlikely-annotations.pony:12:14 appendices-annotations-likely-and-unlikely-annotations.pony:17:19 appendices-annotations-likely-and-unlikely-annotations.pony:22:24 appendices-annotations-likely-and-unlikely-annotations.pony:27:30 --8<-- → runnable--8<-- "appendices-annotations-packed-annotation.pony
:1:3
"
→ runnable--8<-- "appendices-examples-create-arrays-with-values.pony
:5:9
"
→ runnable--8<-- "appendices-examples-enumeration-with-values-with-namespace.pony
:4:6
"
→ runnable--8<-- "appendices-examples-enumeration-with-values.pony
:4:5
"
→ runnable--8<-- "appendices-whitespace-do-a-then-do-a-unary-negation-of-b.pony
:14:15
"
→ runnable--8<-- "appendices-whitespace-subtract-b-from-a.pony
:14:14
"
→ runnable