Improve read me #24
Improve read me #24
Conversation
Converted markdown to Restructured text, so links would display correctly.
|
xref #23 |
There was a problem hiding this comment.
Sorry it took a while for me to get to this.
I would like to start by asking at a high level what you think is missing from the current README. Some of this material seems more suited for an "intro to byterun" blog post or "getting started" guide, but not really the README. I think there is room for improvement but maybe the solution is adding more docs outside of the README.
I have made some line-comments on particular things but would like to better understand what you see the end-goal for the README is so we can work together on getting there.
| fix branch coverage bugs in coverage.py. | ||
|
|
||
|
|
||
| Byterun is a python interpreter written in just 1451 lines of Python. |
There was a problem hiding this comment.
I think the original phrasing around "interpreter" vs "bytecode execution vm" was more clear. While this is technically correct more people will assume this means it is a complete interpreter for Python like PyPy or Jython which is not true and not a goal of this project.
| fix branch coverage bugs in coverage.py. | ||
|
|
||
|
|
||
| Byterun is a python interpreter written in just 1451 lines of Python. |
There was a problem hiding this comment.
We should probably avoid giving a concrete line count in the README, it will just become out of date if we make changes later.
|
|
||
| Byterun is a python interpreter written in just 1451 lines of Python. | ||
| Byterun's goal is to clearly explain Python's design. | ||
| If you want to better understand Python, or you are not quite sure how something in cPYthon works, then Byterun is a great place to start. |
There was a problem hiding this comment.
CPython is spelled with a capital C and P.
|
|
||
|
|
||
| Byterun is a python interpreter written in just 1451 lines of Python. | ||
| Byterun's goal is to clearly explain Python's design. |
There was a problem hiding this comment.
Byterun is more targeted at the CPython bytecode scheme than Python as a language.
| Byterun is a python interpreter written in just 1451 lines of Python. | ||
| Byterun's goal is to clearly explain Python's design. | ||
| If you want to better understand Python, or you are not quite sure how something in cPYthon works, then Byterun is a great place to start. | ||
| Byterun has proven very useful to a number of different projects, `including one by Google <https://github.com/nedbat/byterun/pull/12>`_. |
There was a problem hiding this comment.
I think this may promote the wrong mindset about Byterun. Byterun is a great teaching and learning tool but is not great for actually executing CPython bytecode because performance is not a key concern.
| And from there you can move onto studying cPython, or PyPy, or Jython. | ||
|
|
||
| In the process, you | ||
| will certainly need to refer to `the list of Python bytecodes <https://docs.python.org/2.4/lib/bytecodes.html>`_ |
There was a problem hiding this comment.
We may want to move this to an appendix in documentation outside of the README. As a note, I would use the same version here as the execution model docs. Also 2.4 is very out of date and may not actually work with byterun. You should probably use 2.7.
| excellent introductory article on Byterun written by Alison | ||
| Kaptur. `A Python Interpreter written in Python <http://www.aosabook.org/en/500L/a-python-interpreter-written-in-python.html>`_ | ||
|
|
||
| If you are not sure what a stack machine is, you might even start |
There was a problem hiding this comment.
We may want to write a small explanation of a stack machine in our own docs. I find that with CS concepts on wikipedia it can be hard to tease apart abstract concepts and things that are particular to some runtime/language that the author knows.
| There are a number of python virtual machines. Most Python developers use cPython. cPython includes a virtual machine written in C. Yes it runs Python very fast, but it is a large code base, and difficult to understand. Much better to start by studying Byterun. Then you can move onto cPython. | ||
|
|
||
| If you are interested in Byterun, the first step is to read the | ||
| excellent introductory article on Byterun written by Alison |
There was a problem hiding this comment.
There are two ls in Allison Kaptur's name.
I am very sensitive to properly counting l characters.
|
|
||
| After understanding Alison's Byterun article, you should be able to make sense of | ||
| `the source code for this repository </byterun>`_ | ||
| And from there you can move onto studying cPython, or PyPy, or Jython. |
There was a problem hiding this comment.
byterun will not be much help for PyPy or Jython. Those projects to not use CPython's bytecode.
| with `the Wikipedia article on stack machines. <https://en.wikipedia.org/wiki/Stack_machine>`_ | ||
|
|
||
| After understanding Alison's Byterun article, you should be able to make sense of | ||
| `the source code for this repository </byterun>`_ |
There was a problem hiding this comment.
No need to self-link in the README. If you are reading it you either have the code or are at a place that has the code.
No worries. I understand that this is not your day job. I am also mindful that I have not yet responded to Allison’s excellent comments. Lots to learn before I can reply intelligently.
Great question. Four things are missing. One is context. What are the related issues? Second is motivation. Why does this project exist? Third is an introduction. We should link to Allison’s excellent article. And finally a reading list is needed. What else should a person read if they want to learn more? Maybe the last is easiest for me to answer. I am busy reading everything I can find, digging down into how cPython works. Maybe I also need to read more about PyPy. And in the process, I am creating a curated list of recommended references. In due course I will share it. As for motivation, you say that
I see it as a way to learn how to implement Python on a stack machine. I wonder how others see it? So thanks for the excellent feedback. In due course I will update the proposed README. Warm Regards |
I have improved the README.rst file.
I have linked to a number of important references.
All the links work.
I have added friendly welcoming text.
I have added some history.
If there is anything else you would like me to do to the README. rst file, please let me know.
And of course thanks to all the people who did the really hard work of writing the software.