Refactoring of examples in documentation [Sketch]#130
Conversation
lightmanLP
commented
Jun 8, 2026
lightmanLP
commented
- Было бы неплохо иметь плавный переход между табами с примерами, чтобы видеть появление различий. По крайней мере иметь выравнивание при разных вариантах одного и того же большого примера (Quick start).
- В некоторых местах желательно иметь комментарии к шагам (Quick start).
- В местах с простыми примерами, демонстрирующими одну фичу, удобнее иметь только один blank line отступа для компактности. Чтобы не путаться, можно просто ввести это везде.
- Починить бы подсветку тайпхинтов в виде строк, а то читать тот же Source Reference не удобно.
- В большинстве примеров достаточно оставлять схему и вызов (+ что-то релевантное непосредственно к секции).
- В некоторых местах (Loading) все табы уезжают вместе, что отвлекает.
- В Loading секцию с примером и непосредственно ошибкой удобнее читать вместе, а не по разным табам.
| @@ -1 +1 @@ | |||
| """Decorator mode — auto-load config on instantiation.""" | |||
There was a problem hiding this comment.
This line, I think, needs to be deleted. It's pointless. This line is already there, or should be in the doc.
There was a problem hiding this comment.
It might be moved to a doc of Quick start, because theres no context provided on behavior of auto-load.
Since it is also used in the Introduction, a brief explanation will be required there as well.
There was a problem hiding this comment.
You may proceed if you find it useful and no equivalent string exists in the documentation.
|
|
||
| import dature | ||
|
|
||
| # (our externally-provided data for config) |
| # Step 2: Load it! | ||
| config = AppConfig() | ||
|
|
||
| # PROFIT! |
There was a problem hiding this comment.
We might drop those two, I just added them for consistency of section comments, but I'd prefer to keep first one, because the purpose of setting such envs inside of example wasn't obvious from first look. It isn't that clear until we reach load call (part about loading sources). It clarifies the purpose early on, so we don't need to keep it in head or overthink it.
There was a problem hiding this comment.
You don't need to drop the others, they make sense. Just drop "PROFIT"
| debug: bool = False | ||
|
|
||
|
|
||
| # --8<-- [start:override] |
There was a problem hiding this comment.
Can you expand it from line 10 to the end?
| import dature | ||
|
|
||
|
|
||
| # --8<-- [start:schema] |
There was a problem hiding this comment.
There's no need to explicitly select the schema. In fact, this example seems to need to be split into two files.
2 participants
