add Developer Documentation #48

add Developer Documentation

docs/dev_doc.rst

@@ -0,0 +1,41 @@
+Developer Documentation
+===========================================
+
+For developers, if you want to understand and contribute to the codebase, this section is for you.
+
+It is recommended to read the following materials before diving into the codebase:
+
+- `torchdynamo deepdive <https://www.youtube.com/watch?v=egZB5Uxki0I>`_ : This video explains the motivation and design of torchdynamo. In particular, it mentions how Python bytecode acts like a stack machine, which helps to understand how the bytecode is executed.
+- `Python bytecode documentation <https://docs.python.org/3/library/dis.html>`_ : This documentation explains the Python bytecode instructions. Note that Python bytecode does not guarentee any backward compatibility, so the bytecode instructions may change for every Python versions. We should consider all the supported Python versions when implementing the decompiler.
+- `A Python Interpreter Written in Python <https://aosabook.org/en/500L/a-python-interpreter-written-in-python.html>`_ : This book chapter explains how to write a Python interpreter in Python. It is a good starting point to understand how Python bytecode is executed.
+
+The decompilation process is achieved by executing the Python bytecode and recording the stack and the variables, with the value of the variables represented by their source code.
+
+For example, consider the following simple function:
+
+.. code-block:: python
+
+    def f(a, b):
+        return a + b
+
+It has the following bytecode:
+
+.. code-block:: text
+
+    0 LOAD_FAST                0 (a)
+    2 LOAD_FAST                1 (b)
+    4 BINARY_ADD
+    6 RETURN_VALUE
+
+When we execute the first bytecode `LOAD_FAST`, instead of loading a variable into the stack, we push the variable name ``"a"`` in the stack, which is a string representation of the variable.
+
+When we execute the second bytecode `LOAD_FAST`, likewise, we push the variable name ``"b"`` in the stack.
+
+When we execute the third bytecode `BINARY_ADD`, which intends to add the two variables, we pop the two variables from the stack, and perform the string concatenation ``"a + b"``. The concatenated string is pushed back to the stack.
+
+Finally, when we execute the fourth bytecode `RETURN_VALUE`, we pop the string from the stack, prefix it with the ``return`` keyword, and then we get the decompiled source code ``"return a + b"``.
+
+To accurately decompile the bytecode, we need to faithfully respect the semantics of the Python bytecode instructions. It is noteworthy that the `Python bytecode documentation <https://docs.python.org/3/library/dis.html>`_ can be outdated and inaccurate, too. The golden standard is to refer to the CPython source code and the Python interpreter's behavior. The `torchdynamo source code <https://github.com/pytorch/pytorch/blob/main/torch/_dynamo/symbolic_convert.py>`_ is also a good reference to understand how the Python bytecode is generated by PyTorch.
+
+Should you have any further questions, feel free to ask in the `GitHub Issues <https://github.com/thuml/depyf/issues>`_ section.
+

docs/index.rst

@@ -61,10 +61,13 @@ The following figure shows two typical usages of ``depyf``, and lists all the ge
 
 You can also check `the advanced usages <./index.html>`_ and `frequently asked questions <./faq.html>`_ for more details.
 
+If you'd like to contribute (which we highly appreciate), please read the `developer documentation <./dev_doc.html>`_ section.
+
 .. toctree::
    :maxdepth: 1
    :hidden:
 
    walk_through
    advanced
-   faq
+   faq
+   dev_doc