Author: Maciej Fijalkowski <[email protected]>
Branch: improve-docs-2
Changeset: r62883:b664434c47de
Date: 2013-03-27 01:16 -0700
http://bitbucket.org/pypy/pypy/changeset/b664434c47de/
Log: starts a doc rework
diff --git a/README.rst b/README.rst
--- a/README.rst
+++ b/README.rst
@@ -13,9 +13,9 @@
http://pypy.org/
-The getting-started document will help guide you:
+If you want to help developing PyPy, this document might help you:
- http://doc.pypy.org/en/latest/getting-started.html
+ http://doc.pypy.org/
It will also point you to the rest of the documentation which is generated
from files in the pypy/doc directory within the source repositories. Enjoy
diff --git a/pypy/doc/getting-started-dev.rst b/pypy/doc/getting-started-dev.rst
--- a/pypy/doc/getting-started-dev.rst
+++ b/pypy/doc/getting-started-dev.rst
@@ -1,9 +1,15 @@
-===============================================================================
-Getting Started with the Translation Toolchain and Development Process
-===============================================================================
+============================
+Getting Started with RPython
+============================
.. contents::
+
+This should really write a word of two about **WHAT** is RPython
+XXX
+XXX
+XXX
+
.. _`try out the translator`:
Trying out the translator
diff --git a/pypy/doc/getting-started-python.rst
b/pypy/doc/getting-started-python.rst
--- a/pypy/doc/getting-started-python.rst
+++ b/pypy/doc/getting-started-python.rst
@@ -6,7 +6,7 @@
PyPy's Python interpreter is a very compliant Python
-interpreter implemented in Python. When translated to C, it passes most of
+interpreter implemented in RPython. When compiled, it passes most of
`CPythons core language regression tests`_ and comes with many of the extension
modules included in the standard library including ``ctypes``. It can run large
libraries such as Django_ and Twisted_. There are some small behavioral
@@ -146,6 +146,8 @@
Translating using the CLI backend
+++++++++++++++++++++++++++++++++
+**Note: the CLI backend is no longer maintained**
+
To create a standalone .NET executable using the `CLI backend`_::
./translate.py --backend=cli targetpypystandalone.py
diff --git a/pypy/doc/index.rst b/pypy/doc/index.rst
--- a/pypy/doc/index.rst
+++ b/pypy/doc/index.rst
@@ -1,15 +1,36 @@
-Welcome to PyPy Development
-=============================================
+Welcome to PyPy
+===============
The PyPy project aims at producing a flexible and fast Python_
-implementation. The guiding idea is to translate a Python-level
-description of the Python language itself to lower level languages.
-Rumors have it that the secret goal is being faster-than-C which is
-nonsense, isn't it? `more...`_
+implementation. For the general idea what is pypy, consult the `pypy website`_.
+This page documents entry points into the development of the PyPy project.
+If you just want to use it, consult the `download`_ page on the PyPy website
+and `getting started with pypy`_ document.
-Getting into PyPy ...
-=============================================
+PyPy is written in a language called `RPython`_, which is suitable for
+writing dynamic language interpreters (and not much else).
+`Starting with RPython`_ should provide a reasonable overview if you want
+to learn the language.
+
+**If you want to contribute to PyPy**, please read `how to contribute`_ first.
+PyPy development style is vastly different than most other software projects
+and it usually comes as surprise to most people. What is **not** necessary is
+having academic knowledge from university about writing compilers. Most of
+it does not apply to PyPy at all.
+
+All of the documentation and source code is available under the MIT license,
+unless otherwise specified. Consult `LICENSE`_
+
+.. _`download`: http://pypy.org/download.html
+.. _`getting started with pypy`: getting-started-python.html
+.. _`RPython`: coding-guide.html#RPython
+.. _`Starting with RPython`: getting-started-dev.html
+.. _`how to contribute`: how-to-contribute.html
+.. _`pypy website`: http://pypy.org
+
+Index of various topics:
+========================
* `Getting started`_: how to install and run the PyPy Python interpreter
@@ -26,19 +47,28 @@
* `potential project ideas`_: In case you want to get your feet wet...
Documentation for the PyPy Python Interpreter
-===============================================
+=============================================
New features of PyPy's Python Interpreter and
Translation Framework:
* `Differences between PyPy and CPython`_
- * `What PyPy can do for your objects`_
- * `Continulets and greenlets`_
+ * `What PyPy can do for your objects`_ - transparent proxy documentation
+ * `Continulets and greenlets`_ - documentation about stackless features
* `JIT Generation in PyPy`_
+ * `JIT hooks`_
* `Sandboxing Python code`_
+ * `Garbage collection environment variables`_
Status_ of the project.
+.. _`Differences between PyPy and CPython`: cpython_differences.html
+.. _`What PyPy can do for your objects`: objspace-proxies.html
+.. _`Continulets and greenlets_`: stackless.html
+.. _`JIT Generation in PyPy`: jit/index.html
+.. _`JIT hooks`: jit-hooks.html
+.. _`Sandboxing Python code`: sandbox.html
+.. _`Garbage collection environment variables`: gc_info.html
Mailing lists, bug tracker, IRC channel
=============================================
@@ -83,12 +113,7 @@
Project Documentation
=====================================
-PyPy was funded by the EU for several years. See the `web site of the EU
-project`_ for more details.
-
-.. _`web site of the EU project`: http://pypy.org
-
-architecture_ gives a complete view of PyPy's basic design.
+`architecture`_ gives a complete view of PyPy's basic design.
`coding guide`_ helps you to write code for PyPy (especially also describes
coding in RPython a bit).
@@ -112,12 +137,11 @@
`Glossary`_ of PyPy words to help you align your inner self with
the PyPy universe.
-
Status
===================================
PyPy can be used to run Python programs on Linux, OS/X,
-Windows, on top of .NET, and on top of Java.
+Windows.
To dig into PyPy it is recommended to try out the current
Mercurial default branch, which is always working or mostly working,
instead of the latest release, which is `2.0 beta1`__.
@@ -176,13 +200,21 @@
`configuration documentation`_ describes the various configuration options that
allow you to customize PyPy.
+`pypy on windows`_
+
+`command line reference`_
+
`CLI backend`_ describes the details of the .NET backend.
`JIT Generation in PyPy`_ describes how we produce the Python Just-in-time
Compiler
from our Python interpreter.
+`directory cross-reference`_
-
+.. _`garbage collector`: garbage_collection.html
+.. _`directory cross-reference`: dir-reference.html
+.. _`pypy on windows`: windows.html
+.. _`command line reference`: commandline_ref.html
.. _`FAQ`: faq.html
.. _Glossary: glossary.html
.. _`PyPy video documentation`: video-index.html
@@ -198,7 +230,7 @@
.. _`translation aspects`: translation-aspects.html
.. _`configuration documentation`: config/
.. _`coding guide`: coding-guide.html
-.. _`architecture`: architecture.html
+.. _`Architecture`: architecture.html
.. _`getting started`: getting-started.html
.. _`bytecode interpreter`: interpreter.html
.. _`EU reports`: index-report.html
@@ -211,168 +243,14 @@
.. _`Sandboxing Python code`: sandbox.html
.. _`LICENSE`: https://bitbucket.org/pypy/pypy/src/default/LICENSE
-PyPy directory cross-reference
-------------------------------
-
-Here is a fully referenced alphabetical two-level deep
-directory overview of PyPy:
-
-================================= ============================================
-Directory explanation/links
-================================= ============================================
-`pypy/bin/`_ command-line scripts, mainly
- `pypy/bin/pyinteractive.py`_
-
-`pypy/config/`_ handles the numerous options for building
- and running PyPy
-
-`pypy/doc/`_ text versions of PyPy developer
- documentation
-
-`pypy/doc/config/`_ documentation for the numerous translation
- options
-
-`pypy/doc/discussion/`_ drafts of ideas and documentation
-
-``doc/*/`` other specific documentation topics or tools
-
-`pypy/interpreter/`_ `bytecode interpreter`_ and related objects
- (frames, functions, modules,...)
-
-`pypy/interpreter/pyparser/`_ interpreter-level Python source parser
-
-`pypy/interpreter/astcompiler/`_ interpreter-level bytecode compiler,
- via an AST representation
-
-`pypy/module/`_ contains `mixed modules`_
- implementing core modules with
- both application and interpreter level code.
- Not all are finished and working. Use
- the ``--withmod-xxx``
- or ``--allworkingmodules`` translation
- options.
-
-`pypy/objspace/`_ `object space`_ implementations
-
-`pypy/objspace/std/`_ the StdObjSpace_ implementing CPython's
- objects and types
-
-`pypy/tool/`_ various utilities and hacks used
- from various places
-
-`pypy/tool/algo/`_ general-purpose algorithmic and mathematic
- tools
-
-`pypy/tool/pytest/`_ support code for our `testing methods`_
-
-
-`rpython/annotator/`_ `type inferencing code`_ for
- `RPython`_ programs
-
-`rpython/config/`_ handles the numerous options for RPython
-
-
-`rpython/flowspace/`_ the FlowObjSpace_ implementing
- `abstract interpretation`_
-
-`rpython/rlib/`_ a `"standard library"`_ for RPython_
- programs
-
-`rpython/rtyper/`_ the `RPython Typer`_
-
-`rpython/rtyper/lltypesystem/`_ the `low-level type system`_ for
- C-like backends
-
-`rpython/rtyper/ootypesystem/`_ the `object-oriented type system`_
- for OO backends
-
-`rpython/memory/`_ the `garbage collector`_ construction
- framework
-
-`rpython/translator/`_ translation_ backends and support code
-
-`rpython/translator/backendopt/`_ general optimizations that run before a
- backend generates code
-
-`rpython/translator/c/`_ the `GenC backend`_, producing C code
- from an
- RPython program (generally via the rtyper_)
-
-`rpython/translator/cli/`_ the `CLI backend`_ for `.NET`_
- (Microsoft CLR or Mono_)
-
-`pypy/goal/`_ our `main PyPy-translation scripts`_
- live here
-
-`rpython/translator/jvm/`_ the Java backend
-
-`rpython/translator/tool/`_ helper tools for translation
-
-`dotviewer/`_ `graph viewer`_
-
-``*/test/`` many directories have a test subdirectory
- containing test
- modules (see `Testing in PyPy`_)
-
-``_cache/`` holds cache files from various purposes
-================================= ============================================
-
-.. _`bytecode interpreter`: interpreter.html
-.. _`Testing in PyPy`: coding-guide.html#testing-in-pypy
-.. _`mixed modules`: coding-guide.html#mixed-modules
-.. _`modules`: coding-guide.html#modules
-.. _`basil`: http://people.cs.uchicago.edu/~jriehl/BasilTalk.pdf
-.. _`object space`: objspace.html
-.. _FlowObjSpace: objspace.html#the-flow-object-space
-.. _`transparent proxies`: objspace-proxies.html#tproxy
-.. _`Differences between PyPy and CPython`: cpython_differences.html
-.. _`What PyPy can do for your objects`: objspace-proxies.html
-.. _`Continulets and greenlets`: stackless.html
-.. _StdObjSpace: objspace.html#the-standard-object-space
-.. _`abstract interpretation`:
http://en.wikipedia.org/wiki/Abstract_interpretation
-.. _`rpython`: coding-guide.html#rpython
-.. _`type inferencing code`: translation.html#the-annotation-pass
-.. _`RPython Typer`: translation.html#rpython-typer
-.. _`testing methods`: coding-guide.html#testing-in-pypy
-.. _`translation`: translation.html
-.. _`GenC backend`: translation.html#genc
-.. _`CLI backend`: cli-backend.html
-.. _`py.py`: getting-started-python.html#the-py.py-interpreter
-.. _`translatorshell.py`: getting-started-dev.html#try-out-the-translator
-.. _JIT: jit/index.html
-.. _`JIT Generation in PyPy`: jit/index.html
-.. _`just-in-time compiler generator`: jit/index.html
-.. _rtyper: rtyper.html
-.. _`low-level type system`: rtyper.html#low-level-type
-.. _`object-oriented type system`: rtyper.html#oo-type
-.. _`garbage collector`: garbage_collection.html
-.. _`main PyPy-translation scripts`:
getting-started-python.html#translating-the-pypy-python-interpreter
-.. _`.NET`: http://www.microsoft.com/net/
-.. _Mono: http://www.mono-project.com/
-.. _`"standard library"`: rlib.html
-.. _`graph viewer`: getting-started-dev.html#try-out-the-translator
-
-
.. The following documentation is important and reasonably up-to-date:
.. extradoc: should this be integrated one level up: dcolish?
-
.. toctree::
:maxdepth: 1
:hidden:
- getting-started.rst
- getting-started-python.rst
- getting-started-dev.rst
- windows.rst
- faq.rst
- commandline_ref.rst
- architecture.rst
- coding-guide.rst
- cpython_differences.rst
- garbage_collection.rst
- gc_info.rst
interpreter.rst
objspace.rst
__pypy__-module.rst
diff --git a/pypy/doc/needswork.txt b/pypy/doc/needswork.txt
deleted file mode 100644
--- a/pypy/doc/needswork.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-.. warning::
-
- This documentation needs work (as discussed during the Gothenburg sprint in
2011)
diff --git a/pypy/doc/objspace-proxies.rst b/pypy/doc/objspace-proxies.rst
--- a/pypy/doc/objspace-proxies.rst
+++ b/pypy/doc/objspace-proxies.rst
@@ -5,7 +5,6 @@
.. contents::
-
Thanks to the `Object Space`_ architecture, any feature that is
based on proxying, extending, changing or otherwise controlling the
behavior of all objects in a running program is easy to implement on
_______________________________________________
pypy-commit mailing list
[email protected]
http://mail.python.org/mailman/listinfo/pypy-commit
