Small documentation improvements & quickstart guide #399
Conversation
| HPy unit tests | ||
| ~~~~~~~~~~~~~~ | ||
|
|
||
| HPy usually has tests for each API function. This means that there is lots of |
There was a problem hiding this comment.
this paragraph is just shuffled at the end of this file
|
|
||
| - **Debugging**: it provides an improved debugging experience. Debug mode can be turned | ||
| on at runtime without the need to recompile the extension or the Python running it. | ||
| HPy design is more suitable for automated checks. |
There was a problem hiding this comment.
I shuffled this at the top, shortened the points, and added think "stable ABI" on steroids
| - use tagged pointers to reduce memory footprint | ||
|
|
||
| Where to go next: | ||
| ----------------- |
There was a problem hiding this comment.
I think this could pitch some parts of the documentation depending on what you're looking for: either code samples or some more explanations/details
| embedding | ||
| protocols |
There was a problem hiding this comment.
These two were not a real documentation, but design notes. I don't think it fits in the docs.
There was a problem hiding this comment.
I saw this comment only after my review. Maybe we could move the string stuff to the wiki?
|
|
||
| There are several advantages to write your C extension in HPy: | ||
| - use a tracing garbage collection instead of reference counting | ||
| - remove the global interpreter lock (GIL) to take full advantage of multicore architectures |
There was a problem hiding this comment.
Is this true? Does using HPy make it any easier to be sure code does not have threading problems?
There was a problem hiding this comment.
Yes, good point. This bullet point was here before, I just shuffled it and added "... to take full advantage of multicore architectures".
HPy make it any easier to be sure code does not have threading problems
Depends on the point of view. My line of thinking is that it would make it easier to do the internal changes in CPython that are needed to remove the GIL. Still extensions would have to make sure that they operate correctly without GIL.
I think it still falls into the category of "what is wrong with current C API", although better HPy would not solve the problem as a whole, only a part of it. Explaining all this in detail would make this bullet point too long/complex. I like that "removing GIL" is something that many would clearly understand brings benefits and there is bit of a hype around it now :-) I think this simplification could be fine for such a pitch as the beginning of the documentation?
| @@ -1,443 +0,0 @@ | |||
| bytes/str building API | |||
| ======================= | |||
There was a problem hiding this comment.
Maybe move this into a "design document" section?
There was a problem hiding this comment.
I've linked it to the relevant GitHub issue. I think that having design documents in the "main" user documentation is not good, because:
- it can be misleading and create false expectations
- we should primarily use GitHub issues (or something else, but a single location -- I haven't read it in detail, but I suspect that
str-builder-api.rstis not up-to-date, anyway)
docs/quickstart.rst
Outdated
| @@ -0,0 +1,52 @@ | |||
| HPy Quickstart | |||
| ============= | |||
There was a problem hiding this comment.
Doesn't this duplicate much of the simple example
There was a problem hiding this comment.
Yes, but I think the two can serve slightly different purposes: quickstart -- when I am impatient, I want hands on experience right now, I don't mind following instructions blindly for now, simple example -- when I want some additional context and explanations.
I could not resist adding few explanatory comments to quickstart, but I tried to keep them very short.
Co-authored-by: Matti Picus <matti.picus@gmail.com>
|
Thanks for review @mattip! If the CI jobs pass (modulo cppcheck), I'll go ahead with merge and we can discuss these later (maybe on a dev call):
|
|
Cool, thanks |
No description provided.