[pypy-svn] r12413 - pypy/dist/pypy/documentation

hpk at codespeak.net hpk at codespeak.net
Tue May 17 15:43:08 CEST 2005 

Author: hpk
Date: Tue May 17 15:43:08 2005
New Revision: 12413

Modified:
   pypy/dist/pypy/documentation/coding-guide.txt
   pypy/dist/pypy/documentation/getting_started.txt
   pypy/dist/pypy/documentation/svn-help.txt
Log:
issue37 in-progress
issue15 in-progress 

(probably the world will implode trying to use two issue references 
but i had to try it :-) 

M    documentation/getting_started.txt
    - refactor and streamlining 
    - detailed version -> interesting starting points 
    - reference svn-help  
    
M    documentation/svn-help.txt
    - cut it a bit by not repeating endlessly where to find PyPy sources 

M    documentation/coding-guide.txt
    - scrap out ReST help and simply reference the ReST
      quickstart (it's better and you can start by looking
      at existing documentation anyway) 



Modified: pypy/dist/pypy/documentation/coding-guide.txt
==============================================================================
--- pypy/dist/pypy/documentation/coding-guide.txt	(original)
+++ pypy/dist/pypy/documentation/coding-guide.txt	Tue May 17 15:43:08 2005
@@ -489,6 +489,8 @@
 .. _`this document`: svn-help.html
 
 
+.. _`using development tracker`: 
+
 Using the development bug/feature tracker
 =========================================
 
@@ -536,8 +538,10 @@
 .. _`roundup`: http://roundup.sf.net
 
 
-Test Design
-=============
+.. _`testing in PyPy`: 
+
+Testing in PyPy
+=============== 
 
 Our tests are based on the new `py.test`_ tool which lets you write
 unittests without boilerplate.  All tests of modules
@@ -625,57 +629,24 @@
   upon import will make sure that sys.path contains the directory
   where 'pypy' is in. 
 
-PyPy Documentation
-==================
-
-Adding documentation 
--------------------- 
-
-Please add new or updated documentation by checking it in to the appropriate 
-directory in subversion, usually under 
-http://codespeak.net/svn/pypy/dist/pypy/documentation 
-
-+ Remember to run ``svn up`` **before** doing any commit.
-+ All filenames should be lowercase, and documentation should be .txt files.
-+ Mark-up the documentation with reST so it can generate a pretty html version.
-+ On the server side a commit on the doc-subtree will immediately update the webpage. 
-
-*Note*  If you don't markup the textfile, it'll still be checked in, but when docutils 
-runs the parser, it'll look ugly on the website. So run docutils yourself before you commit it. 
-
-Some reST basics:
------------------
+.. _`change documentation and website`: 
 
-There should be a title on your page. Do it like this::
+Changing documentation and website 
+================================== 
 
- Here is my Title
- ==================
+documentation/website files in your local checkout 
+---------------------------------------------------
 
- Here is a section title
- -------------------------
+Most of the PyPy's documentation and website is kept in 
+`pypy/documentation` and `pypy/documentation/website` respectively. 
+You can simply edit or add '.txt' files which contain ReST-markuped 
+files.  Here is a `ReST quickstart`_ but you can also just look
+at the existing documentation and see how things work. 
 
-Make sure you have a blank line after your = or - lines or it will give you an error.
-For marking a block of code so it'll look right, you can::
+.. _`ReST quickstart`: http://docutils.sourceforge.net/docs/rst/quickref.html
 
- Put a line of text ending with ::
-  indent your code at least one space
-  my code
-    more code
-      even more code
-  still more code
-
-End of the "block" occurs whenever you unindent back to the same level as the
-text with the ``::`` at the end.
-
-Using an underscore after a word like ``this_`` will make reST think you want a hyperlink.
-To avoid that (especially with things like ``wrap_``), you can use the `` back quote ``
-to mark it as plain text.
-
-You can get more info on reST markup at http://docutils.sourceforge.net/docs/rst/quickref.html
-
-
-Automatically testing documentation changes
-------------------------------------------- 
+Automatically test documentation/website changes
+------------------------------------------------
 
 .. _`docutils home page`: 
 .. _`docutils`: http://docutils.sourceforge.net/ 
@@ -688,7 +659,7 @@
     python ../test_all.py 
 
 If you see no failures chances are high that your modifications at least 
-don't produce ReST-errors or wron local references.  A side effect of running
+don't produce ReST-errors or wrong local references.  A side effect of running
 the tests is that you have `.html` files in the documentation directory 
 which you can point your browser to! 
 
@@ -699,3 +670,4 @@
 
 which will check that remote URLs are reachable.  
 
+

Modified: pypy/dist/pypy/documentation/getting_started.txt
==============================================================================
--- pypy/dist/pypy/documentation/getting_started.txt	(original)
+++ pypy/dist/pypy/documentation/getting_started.txt	Tue May 17 15:43:08 2005
@@ -33,7 +33,8 @@
 really was on compliancy: PyPy passes around `90% of CPythons core 
 language regression tests`_. 
 
-You may go to the more `detailed version`_ of this two-liner. 
+Have a look at `interesting starting points`_ 
+for guidance on how to continue. 
 
 .. _`90% of CPythons core language regression tests`: http://codespeak.net/~hpk/pypy-testresult/ 
 
@@ -57,17 +58,19 @@
 
 have fun :-) 
 
-If you want to know more how to get started with subversion read this_. 
-You may also want to go to the more `detailed version`_ of this 
-two-liner below.
+We have some `help on installing subversion`_ for PyPy. 
+Have a look at `interesting starting points`_ 
+for some guidance on how to continue. 
+
+.. _`help on installing subversion`: svn-help.html
 
 Understanding PyPy's architecture
 ---------------------------------
 
-For in-depth information about architecture and coding style head over 
-to the `documentation section`_ where you'll find lots of interesting 
-information.  Additionally, in true hacker spirit, you may just 
-`start reading sources`_ . 
+For in-depth information about architecture and coding documentation 
+head over to the `documentation section`_ where you'll find lots of 
+interesting information.  Additionally, in true hacker spirit, you 
+may just `start reading sources`_ . 
 
 .. _`documentation section`: index.html 
 
@@ -83,10 +86,20 @@
 testing tool that we are using and enhancing for PyPy.   
 
 .. _`py.test`: http://codespeak.net/py/current/doc/test.html 
-.. _`detailed version`: 
+.. _`interesting starting points`: 
+
+Filing bugs or feature requests 
+-------------------------------
+
+You may file `bug reports`_ on our issue tracker which is
+also accessible through the 'issues' top menu of 
+the PyPy website.  `using the development tracker`_ has 
+more detailed information on specific features of the tracker. 
+
+.. _`using the development tracker`: coding-guide.html#using-development-tracker
 
-The long'n detailed version of how to use PyPy
-==============================================
+Interesting Starting Points in PyPy 
+===================================
 
 The following assumes that you have successfully downloaded and exctracted the
 PyPy release or have checked out PyPy using svn. It assumes that you are in
@@ -162,6 +175,7 @@
 
 .. _`installed py.test`: http://codespeak.net/py/current/doc/getting_started.html
 
+
 Trying out the translator
 ------------------------- 
 
@@ -269,15 +283,18 @@
 To learn more
 ------------- 
 
-*  To learn more about PyPy and its development process, head
-   read around in the documentation_ and the wiki_, and consider 
-   subscribing to the `mailing lists`_ (or simply
-   read the archives online) or show up irc.freenode.net:6667, channel #pypy.
-   The logs of the channel can be found at http://nimrod.terra-link.net/pypy/_.
-
-*  To help PyPy become Python-the-next-generation, you may write some 
-   `unit tests`_ and file some `bug reports`_.
+* To learn more about PyPy and its development process,  
+  read around in the documentation_ and consider 
+  subscribing to the `mailing lists`_ (or simply
+  read the archives online) 
+  
+* show up on irc.freenode.net:6667, channel #pypy and ask
+  questions.  The logs of the channel can be found at 
+  http://nimrod.terra-link.net/pypy/_.
 
+* To help PyPy become Python-the-next-generation, you 
+  are invited to participate in its development. 
+   
 .. _optionaltool: 
 
 Additional Tools for running (and hacking) PyPy 
@@ -351,4 +368,3 @@
 
 
 .. _subversion: svn-help.html
-.. _this: svn-help.html

Modified: pypy/dist/pypy/documentation/svn-help.txt
==============================================================================
--- pypy/dist/pypy/documentation/svn-help.txt	(original)
+++ pypy/dist/pypy/documentation/svn-help.txt	Tue May 17 15:43:08 2005
@@ -1,17 +1,9 @@
 
-subversion
-========== 
+Installing subversion for PyPy 
+============================== 
 
-
-The PyPy codebase, documentation and web pages are controlled by subversion.
-If you already know how to use it here is the URL you need to interact
-with subversion:
-
-``http://codespeak.net/svn/pypy/dist``
-
-If you don't know what to do then Jens-Uwe Mager has prepared some 
-installation files which should help you to install subversion on
-your computer. 
+Jens-Uwe Mager has prepared some installation files which should 
+help you to install subversion on your computer. 
 
 + Download Unix source tarball or prepackaged versions_ for MacOS, Windows, FreeBSD and Linux
 
@@ -28,8 +20,6 @@
 
 + Debian instructions below...
 
-btw, HowToInstallServer_ sketches how to install a subversion server on Linux (not as easy as the client install). You don't need to install server side files to get your client going. 
-
 Getting started
 -----------------

More information about the Pypy-commit mailing list