How-To Update for docs. #819
Conversation
… section. Added a tour of the code. Fixed a grammar error.
docs/how-to/builtins.rst
Outdated
| @@ -1,104 +1,138 @@ | |||
| Implementing Python Built-ins in JavaScript | |||
| =========================================== | |||
|
|
|||
| Python's builtins give Python its trademark magical feel. If you're new to Python, read up on them here: https://docs.python.org/3/library/functions.html | |||
There was a problem hiding this comment.
This would be better as an inline link, rather than a raw URL
docs/how-to/builtins.rst
Outdated
| @@ -1,104 +1,138 @@ | |||
| Implementing Python Built-ins in JavaScript | |||
| =========================================== | |||
|
|
|||
| Python's builtins give Python its trademark magical feel. If you're new to Python, read up on them here: https://docs.python.org/3/library/functions.html | |||
|
|
|||
| Most builtins have already been added to the project, but many do not follow the spec outlined below. | |||
There was a problem hiding this comment.
Avoid colloquial abbreviations; specification, not spev. Although in this case, "description" is probably more accurate; it's not really a formal spec.
docs/how-to/builtins.rst
Outdated
| var <fn> = function(<args>, <kwargs>) { | ||
| // These builtins are designed to be used only inside Batavia, as such they need to ensure | ||
| // they are being used in a compatible manner. | ||
| // Example: <fn> accepts exactly one argument, and no keyword arguments |
There was a problem hiding this comment.
Since we're cleaning this up... I'm not wild about using "" as an example. It's potentially confusing, since as written, it's not valid Javascript or Python syntax. I'd rather use an actual concrete example, with a preface note that says "we're going to use abs() as an example here; abs() is already implemented, but the pattern will be the same for any other builtin". (Substitute abs() for whatever builtin makes sense in the content)
docs/how-to/tour.rst
Outdated
| Core Code | ||
| ********* | ||
|
|
||
| Batavia implements the Python native types, builtins, and standard library partially in JavaScript. |
There was a problem hiding this comment.
This could be a a little clearer - "the core language (types, builtins and the core interpreter) are all javascript, as well those portions of the standard library that depend on system services".
docs/how-to/tour.rst
Outdated
|
|
||
| Support | ||
| ******* | ||
| You'll also notice folders for tests, docs, and a few other bits and bobs, like ``testserver``, which is |
There was a problem hiding this comment.
Avoid the colloquial - "bits and bobs"
docs/how-to/tour.rst
Outdated
| Support | ||
| ******* | ||
| You'll also notice folders for tests, docs, and a few other bits and bobs, like ``testserver``, which is | ||
| a Django project that allows code execution from your browser. Contributions to the |
There was a problem hiding this comment.
might be better to describe testserver as a sample deployment that lets you test Batavia.
docs/how-to/tour.rst
Outdated
| This contains all of the native Python builtin functions, like ``str``, ``len``, and ``iter``. | ||
|
|
||
| When dealing with Python types, many of the native JavaScript operations have been modified to | ||
| try to use builtins first. For instance, .toString() will often just call the object's __str__ if |
There was a problem hiding this comment.
code markup on tostring and str
docs/how-to/tour.rst
Outdated
| core/callables.js | ||
| ^^^^^^^^^^^^^^^^^ | ||
|
|
||
| These methods ensure that all Python code is executed using the proper __call__ procedure, which could be |
| Your goal is to mimic the CPython implementation as much as possible. If you do so, you'll often fix multiple issues at once. Here's some tips: | ||
|
|
||
| * The original implementation is documented in detail at https://docs.python.org/3/ -- reading up there will definitely improve your understanding. | ||
| * If you're inherting your class from JavaScript, which is very common, you get JavaScript's internal methods for free. Oftentimes, they can be left as is or lightly wrapped. |
There was a problem hiding this comment.
@awildtechno Tiny nitpick: inherting I think could be inheriting?
I'm also not sure if it makes sense to add something referring to tox / tox.ini or https://github.com/beeware/beekeeper (could be in a later PR though)?
Otherwise in my quick overview before sleep, this PR looks awesome and way better than what I just started writing, will definitely enjoy going through it in more depth when PyConAU dev sprints continue tomorrow!
Docs felt a bit rusty. I decided to add some pages. I tried to think of what I would've liked to know on my first commit, and I included some of the questions I had to have addressed by the team. Please let me know what you think and if there's any sections that could be added/improved.
Possible issues: