Author: Rami Chowdhury <[email protected]>
Branch: improve-docs
Changeset: r66367:85eb4f2b2c2d
Date: 2013-08-27 17:54 +0100
http://bitbucket.org/pypy/pypy/changeset/85eb4f2b2c2d/
Log: (mjacob, necaris) Improve documentation index page
Add a getting started section, factor out installation / building to
their own sections, and update links.
diff --git a/pypy/doc/getting-started.rst b/pypy/doc/getting-started.rst
--- a/pypy/doc/getting-started.rst
+++ b/pypy/doc/getting-started.rst
@@ -4,31 +4,10 @@
.. contents::
-What is PyPy ?
---------------
-
-In common parlance, PyPy has been used to mean two things. The first is the
-:doc:`RPython translation toolchain <rpython:translation>`, which is a
framework for generating
-dynamic programming language implementations. And the second is one
-particular implementation that is so generated --
-an implementation of the Python_ programming language written in
-Python itself. It is designed to be flexible and easy to experiment with.
-
-This double usage has proven to be confusing, and we are trying to move
-away from using the word PyPy to mean both things. From now on we will
-try to use PyPy to only mean the Python implementation, and say the
-:doc:`RPython translation toolchain <rpython:translation>` when we mean the
framework. Some older
-documents, presentations, papers and videos will still have the old
-usage. You are hereby warned.
-
-We target a large variety of platforms, small and large, by providing a
-compiler toolsuite that can produce custom Python versions. Platform, memory
-and threading models, as well as the JIT compiler itself, are aspects of the
-translation process - as opposed to encoding low level details into the
-language implementation itself. :doc:`more... <architecture>`
.. _Python: http://docs.python.org/reference/
+:doc:`Downloading and installing PyPy <install>`
Just the facts
--------------
@@ -105,6 +84,8 @@
.. _pip: http://pypi.python.org/pypi/pip
+
+
Clone the repository
~~~~~~~~~~~~~~~~~~~~
diff --git a/pypy/doc/index-old.rst b/pypy/doc/index-old.rst
deleted file mode 100644
--- a/pypy/doc/index-old.rst
+++ /dev/null
@@ -1,127 +0,0 @@
-Welcome to PyPy
-===============
-
-The PyPy project aims to produce a flexible and fast Python_
-implementation. This page documents the development of the PyPy
-project itself. If you don't know what PyPy is, consult the `PyPy
-website`_. If you just want to use PyPy, consult the `download`_ page
-and the :doc:`getting-started-python` documents. If you want to help
-develop PyPy -- keep reading!
-
-PyPy is written in a language called `RPython`_, which is suitable for
-writing dynamic language interpreters (and not much else). RPython is
-a subset of Python and is itself written in Python. If you'd like to
-learn more about RPython, `XXXX` should provide a
-reasonable overview.
-
-**If you would like to contribute to PyPy**, please read :doc:`how to
-contribute <how-to-contribute>` first. PyPy's development style is somewhat
different to
-that of many other software projects and it often surprises
-newcomers. What is **not** necessary is an academic background from
-university in writing compilers -- much of it does not apply to PyPy
-any way.
-
-All of the documentation and source code is available under the MIT license,
-unless otherwise specified. Consult :source:`LICENSE`.
-
-.. _Python: http://python.org/
-.. _download: http://pypy.org/download.html
-.. _PyPy website: http://pypy.org/
-.. _RPython: http://rpython.readthedocs.org/
-
-.. toctree::
- :hidden:
-
- getting-started-python
- how-to-contribute
-
-
-Index of various topics:
-------------------------
-
-* :doc:`getting-started`: how to install and run the PyPy Python interpreter
-
-* :doc:`FAQ <faq>`: some frequently asked questions.
-
-* `Release 2.1.0`_: the latest official release
-
-* `PyPy Blog`_: news and status info about PyPy
-
-* :doc:`Papers <extradoc>`: Academic papers, talks, and related projects
-
-* `speed.pypy.org`_: Daily benchmarks of how fast PyPy is
-
-* :doc:`project-ideas`: In case you want to get your feet wet...
-
-* :doc:`More stuff <project-documentation>`: this is a collection of
documentation that's there, but not
- particularly organized
-
-.. _PyPy blog: http://morepypy.blogspot.com/
-.. _Release 2.1.0: http://pypy.org/download.html
-.. _speed.pypy.org: http://speed.pypy.org
-
-.. toctree::
- :hidden:
-
- getting-started
- faq
- extradoc
- project-ideas
- project-documentation
-
-
-Documentation for the PyPy Python Interpreter
----------------------------------------------
-
-New features of PyPy's Python Interpreter and
-Translation Framework:
-
- * :doc:`cpython_differences`
- * :doc:`objspace-proxies` - transparent proxy documentation
- * :doc:`Continulets and greenlets <stackless>` - documentation about
stackless features
- * :doc:`jit-hooks`
- * :doc:`sandbox`
- * :doc:`Garbage collection environment variables <gc_info>`
-
-.. toctree::
- :hidden:
-
- cpython_differences
- objspace-proxies
- stackless
- jit-hooks
- sandbox
- gc_info
-
-
-.. _contact:
-
-Mailing lists, bug tracker, IRC channel
----------------------------------------------
-
-* `Development mailing list`_: development and conceptual
- discussions.
-
-* `Mercurial commit mailing list`_: updates to code and
- documentation.
-
-* `Development bug/feature tracker`_: filing bugs and feature requests.
-
-* **IRC channel #pypy on freenode**: Many of the core developers are hanging
out
- at #pypy on irc.freenode.net. You are welcome to join and ask questions
- (if they are not already developed in the :doc:`FAQ <faq>`).
- You can find logs of the channel here_.
-
-.. _development mailing list: http://python.org/mailman/listinfo/pypy-dev
-.. _Mercurial commit mailing list:
http://python.org/mailman/listinfo/pypy-commit
-.. _development bug/feature tracker: https://bugs.pypy.org
-.. _here: http://tismerysoft.de/pypy/irc-logs/pypy
-
-
-Meeting PyPy developers
------------------------
-
-The PyPy developers are organizing sprints and presenting results at
-conferences all year round. They will be happy to meet in person with
-anyone interested in the project. Watch out for sprint announcements
-on the `development mailing list`_.
diff --git a/pypy/doc/index.rst b/pypy/doc/index.rst
--- a/pypy/doc/index.rst
+++ b/pypy/doc/index.rst
@@ -2,28 +2,41 @@
================================
Welcome to the documentation for PyPy, a fast_, compliant alternative
-implementation of the Python_ language. If you don't know what PyPy is,
-consult the `PyPy website`_.
+implementation of the Python_ language.
-PyPy is written using the RPython toolchain. RPython enables writing dynamic
-language interpreters in a subset of Python which can be translated to C code
-including an automatically generated JIT for the implemented language. If you
-want to learn more about RPython, see the `RPython website`_.
+* If you want to find out more about what PyPy is, have a look at our
:doc:`introduction <introduction>`
+ or consult the `PyPy website`_.
+
+* If you're interested in trying PyPy out, check out the :doc:`installation
instructions <install>`.
+
+* If you want to help develop PyPy, please have a look at :doc:`how to
contribute <how-to-contribute>`
+ and get in touch (:ref:`contact`)!
+
+All of the documentation and source code is available under the MIT license,
+unless otherwise specified. Consult :source:`LICENSE`.
.. _fast: http://speed.pypy.org
.. _Python: http://python.org/
.. _PyPy website: http://pypy.org/
-.. _RPython website: http://rpython.readthedocs.org/
-User documentation
-------------------
+Getting Started
+---------------
.. toctree::
:maxdepth: 1
+ introduction
install
build
+ faq
+
+Using PyPy
+----------
+
+.. toctree::
+ :maxdepth: 1
+
cpython_differences
gc_info
jit-hooks
@@ -37,15 +50,28 @@
-------------------------
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
+
+ how-to-contribute
+ project-ideas
+ project-documentation
+.. TODO: audit ^^
+
+
+.. TODO: Fill this in
Academical stuff
----------------
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
+ extradoc
+.. TODO: Remove this? Or fill it with links to papers?
+
+
+.. _contact:
Contact
-------
@@ -83,4 +109,3 @@
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
-
diff --git a/pypy/doc/install.rst b/pypy/doc/install.rst
--- a/pypy/doc/install.rst
+++ b/pypy/doc/install.rst
@@ -1,2 +1,78 @@
Downloading and Installing PyPy
===============================
+
+Download a pre-built PyPy
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The quickest way to start using PyPy is to download a prebuilt binary for your
+OS and architecture. You can either use the `most recent release`_ or one of
+our `development nightly build`_. Please note that the nightly builds are not
+guaranteed to be as stable as official releases, use them at your own risk.
+
+.. _most recent release: http://pypy.org/download.html
+.. _development nightly build: http://buildbot.pypy.org/nightly/trunk/
+
+
+Installing PyPy
+~~~~~~~~~~~~~~~
+
+PyPy is ready to be executed as soon as you unpack the tarball or the zip
+file, with no need to install it in any specific location::
+
+ $ tar xf pypy-2.1.tar.bz2
+ $ ./pypy-2.1/bin/pypy
+ Python 2.7.3 (480845e6b1dd, Jul 31 2013, 11:05:31)
+ [PyPy 2.1.0 with GCC 4.4.3] on linux2
+ Type "help", "copyright", "credits" or "license" for more information.
+ And now for something completely different: ``PyPy is an exciting
technology
+ that lets you to write fast, portable, multi-platform interpreters with
less
+ effort''
+ >>>>
+
+If you want to make PyPy available system-wide, you can put a symlink to the
+``pypy`` executable in ``/usr/local/bin``. It is important to put a symlink
+and not move the binary there, else PyPy would not be able to find its
+library.
+
+If you want to install 3rd party libraries, the most convenient way is to
+install distribute_ and pip_:
+
+ $ curl -O http://python-distribute.org/distribute_setup.py
+
+ $ curl -O https://raw.github.com/pypa/pip/master/contrib/get-pip.py
+
+ $ ./pypy-2.1/bin/pypy distribute_setup.py
+
+ $ ./pypy-2.1/bin/pypy get-pip.py
+
+ $ ./pypy-2.1/bin/pip install pygments # for example
+
+Third party libraries will be installed in ``pypy-2.1/site-packages``, and
+the scripts in ``pypy-2.1/bin``.
+
+
+Installing using virtualenv
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is often convenient to run pypy inside a virtualenv. To do this
+you need a recent version of virtualenv -- 1.6.1 or greater. You can
+then install PyPy both from a precompiled tarball or from a mercurial
+checkout::
+
+ # from a tarball
+ $ virtualenv -p /opt/pypy-c-jit-41718-3fb486695f20-linux/bin/pypy
my-pypy-env
+
+ # from the mercurial checkout
+ $ virtualenv -p /path/to/pypy/pypy/translator/goal/pypy-c my-pypy-env
+
+Note that bin/python is now a symlink to bin/pypy.
+
+.. _distribute: http://www.python-distribute.org/
+.. _pip: http://pypi.python.org/pypi/pip
+
+
+Building PyPy yourself
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you're interested in getting more involved, or doing something different
with
+PyPy, consult `the build instructions <build>`.
diff --git a/pypy/doc/introduction.rst b/pypy/doc/introduction.rst
new file mode 100644
--- /dev/null
+++ b/pypy/doc/introduction.rst
@@ -0,0 +1,22 @@
+What is PyPy?
+=============
+
+In common parlance, PyPy has been used to mean two things. The first is the
+:doc:`RPython translation toolchain <rpython:translation>`, which is a
framework for generating
+dynamic programming language implementations. And the second is one
+particular implementation that is so generated --
+an implementation of the Python_ programming language written in
+Python itself. It is designed to be flexible and easy to experiment with.
+
+This double usage has proven to be confusing, and we are trying to move
+away from using the word PyPy to mean both things. From now on we will
+try to use PyPy to only mean the Python implementation, and say the
+:doc:`RPython translation toolchain <rpython:translation>` when we mean the
framework. Some older
+documents, presentations, papers and videos will still have the old
+usage. You are hereby warned.
+
+We target a large variety of platforms, small and large, by providing a
+compiler toolsuite that can produce custom Python versions. Platform, memory
+and threading models, as well as the JIT compiler itself, are aspects of the
+translation process - as opposed to encoding low level details into the
+language implementation itself. :doc:`more... <architecture>`
diff --git a/pypy/doc/project-documentation.rst
b/pypy/doc/project-documentation.rst
--- a/pypy/doc/project-documentation.rst
+++ b/pypy/doc/project-documentation.rst
@@ -79,11 +79,3 @@
config/index
commandline_ref
dir-reference
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
-* :ref:`glossary`
_______________________________________________
pypy-commit mailing list
[email protected]
http://mail.python.org/mailman/listinfo/pypy-commit
