Add howtostart and helloworld document

Author: riverfor

docs/_sources/en/howtostart.txt docs/_sources/en/guide.txtdocs/_sources/en/howtostart.txt renamed to docs/_sources/en/guide.txt

@@ -1,16 +1,18 @@
 QPython Getting started
-=============
+==========================
 How to start quickly ? Just follow the following steps:
 
-* `QPython: How To Start <http://wiki.qpython.org/doc/how-to-start>`_
-* `QPython － Quick Start <http://wiki.qpython.org/doc/quick-start>`_
-* `Writing "Hello World" <http://wiki.qpython.org/doc/hello-world>`_
+.. toctree::
+   :maxdepth: 2
+
+   guide_howtostart
+   guide_helloworld
 
 
 Programming Guide
-===================
+========================
 
-If you are able to program, you want to know more about how to complex programming through qpython, just follow these steps:
+If you you want to know more about how to program through qpython, just follow these steps:
 
 
 .. toctree::

docs/_sources/en/guide_helloworld.txt

@@ -0,0 +1,121 @@
+Writing "Hello World"
+========================
+
+
+Hello world
+----------------
+.. image:: ../_static/guide_helloworld_pic1.png
+   :alt: hello world
+
+Well, after you became a bit more familiar with QPython, let's create our first program in QPython. Obviously, it will be `helloworld.py`. ;)
+
+Start QPython, open editor and enter the following code:
+
+::
+
+    import androidhelper
+    droid = androidhelper.Android()
+    droid.makeToast('Hello, Username!')
+
+No wonder, it's just similar to any other hello-world program. When executed, it just shows pop-up message on the screen (see screenshot on the top). Anyway, it's a good example of QPython program.
+
+SL4A library
+------------
+
+It begins with *import androidhelper* — the most useful module in QPython, which encapsulates almost all interface with Android, available in Python. Any script developed in QPython starts with this statement (at least if it claims to communicate with user). Read more about Python library `here <http://docs.python.org/2.7/library/intro.html>`_ and import statement `here <http://docs.python.org/2.7/reference/simple_stmts.html#import>`_
+
+By the way, if you're going to make your script compatible with SL4A, you should replace the first line with the following code (and use `android` instead `androidhelper` further in the program):
+
+::
+
+    try:
+        import androidhelper as android
+    except ImportError:
+        import android
+
+Ok, next we're creating an object `droid` (actually a class), it is necessary to call RPC functions in order to communicate with Android.
+
+And the last line of our code calls such function, `droid.makeToast()`, which shows a small pop-up message (a "toast") on the screen.
+
+Well, let's add some more functionality. Let it ask the user name and greet them.
+
+More samples
+---------------
+We can display a simple dialog box with the title, prompt, edit field and buttons **Ok** and **Cancel** using `dialogGetInput` call. Replace the last line of your code and save it as `hello1.py`:
+
+::
+
+    import androidhelper
+    droid = androidhelper.Android()
+    respond = droid.dialogGetInput("Hello", "What is your name?")
+
+Well, I think it should return any respond, any user reaction. That's why I wrote `respond = ...`. But what the call actually returns? Let's check. Just add `print` statement after the last line:
+
+::
+
+    import androidhelper
+    droid = androidhelper.Android()
+    respond = droid.dialogGetInput("Hello", "What is your name?")
+    print respond
+
+Then save and run it... 
+
+Oops! Nothing printed? Don't worry. Just pull notification bar and you will see "QPython Program Output: hello1.py" — tap it!
+
+
+As you can see, `droid.dialogGetInput()` returns a JSON object with three fields. We need only one — `result` which contains an actual input from user.
+
+Let's add script's reaction:
+
+::
+
+    import androidhelper
+    droid = androidhelper.Android()
+    respond = droid.dialogGetInput("Hello", "What is your name?")
+    print respond
+    message = 'Hello, %s!' % respond.result
+    droid.makeToast(message)
+
+Last two lines (1) format the message and (2) show the message to the user in the toast. See `Python docs <http://docs.python.org/2.7/tutorial/inputoutput.html?highlight=format%20operator#old-string-formatting>`_ if you still don't know what `%` means.
+
+Wow! It works! ;)
+
+Now I'm going to add a bit of logic there. Think: what happen if the user clicks **Cancel** button, or clicks **Ok** leaving the input field blank?
+
+You can play with the program checking what contains `respond` variable in every case.
+
+First of all, I want to put text entered by user to a separate variable: `name = respond.result`. Then I'm going to check it, and if it contains any real text, it will be considered as a name and will be used in greeting. Otherwise another message will be shown. Replace fifth line `message = 'Hello, %s!' % respond.result` with the following code:
+
+::
+
+    name = respond.result
+    if name:
+        message = 'Hello, %s!' % name
+    else:
+        message = "Hey! And you're not very polite, %Username%!"
+
+Use **<** and **>** buttons on the toolbar to indent/unindent lines in if-statement (or just use space/backspace keys). You can read more about indentation in Python `here <http://docs.python.org/2.7/tutorial/introduction.html?highlight=indent#first-steps-towards-programming>`_; if-statement described `here <http://docs.python.org/2.7/tutorial/controlflow.html#if-statements>`_.
+
+First of all, we put user input to the variable `name`. Then we check does `name` contain anything? In case the user left the line blank and clicked **Ok**, the return value is empty string `''`. In case of **Cancel** button pressed, the return value is `None`. Both are treated as false in if-statement. So, only if `name` contans anything meaninful, then-statement is executed and greeting "Hello, ...!" shown. In case of empty input the user will see "Hey! And you're not very polite, %Username%!" message.
+
+Ok, here is the whole program:
+
+::
+
+    import androidhelper
+    droid = androidhelper.Android()
+    respond = droid.dialogGetInput("Hello", "What is your name?")
+    print respond
+    name = respond.result
+    if name:
+        message = 'Hello, %s!' % name
+    else:
+        message = "Hey! And you're not very polite, %Username%!"
+    droid.makeToast(message)
+
+
+`Thanks dmych offer the first draft in his blog <http://onetimeblog.logdown.com/posts/2014/01/23/first-program-in-qpython>`_
+
+
+
+

docs/_sources/en/guide_howtostart.txt

@@ -0,0 +1,134 @@
+QPython: How To Start
+========================
+Now, I will introduce the QPython's features through it's interfaces.
+
+1. Dashboard
+------------------
+
+.. image:: ../_static/guide_howtostart_pic1.png
+   :alt: QPython start
+
+
+After you installed QPython, start it in the usual way by tapping its icon in the menu. Screenshot on the top of this post shows what you should see when QPython just started. 
+
+**Start button**
+
+By tapping the big button with Python logo in the center of the screen you can 
+
+**Launch your local script or project**
+
+*Get script from QR code* (funny brand new way to share and distribute your code, you can create QRCode through `QPython's QRCode generator <http://qpython.com/#qrcode>`_
+
+Now you can install many 3rd libaries ( pure python libraries mainly ) through pip_console.py script.
+
+If you want QPython to run some script of project when you click the start button, you can make it by setting default program in setting activity.
+
+
+**Developer kit dashboard**
+
+If you swipe to the left instead of tapping, you will see another (second) main screen of QPython *(Pic. 2)*. As for me, it is much more useful and comfortable for developer.
+
+.. image:: ../_static/guide_howtostart_pic2.png
+   :alt: QPython develop dashboard
+
+
+Tools available here:
+
+* **Console** — yes, it's regular Python console, feel free to comunicate with interpreter directly
+* **Editor** — QPython has a nice text editor integrated with the rest, you can write code and run it without leaving the application
+* **My QPython** — here you can find your scripts and projects
+* **System** — maintain libraries and components: install and uninstall them
+* **Package Index** opens the page `QPyPI <http://qpypi.qpython.org/>`_ in browser allowing to install packages listed there
+* **Community** leads to `QPython.org <http://qpython.org/>`_ page. Feel free to join or ask&answer questions in the QPython community.
+
+By long clicking on the console or editor, you have chance to create the shortcut on desktop which allow you enter console or editor directly.
+
+Next, let's see the console and the editor. 
+
+2. Console and editor
+-------------------------
+
+.. image:: ../_static/guide_howtostart_pic3.png
+   :alt: QPython console
+
+
+As I said before, there is an ordinary Python console. Many people usually use it to explore objects' properties, consult about syntax and test their ideas. You can type your commands directly and Python interpreter will execute them. You can open additional consoles by tapping the plus button (1) and usedrop-down list on the upper left corner to switch between consoles (2). To close the console just tap the close button (3).
+
+.. image:: ../_static/guide_howtostart_pic4.png
+   :alt: QPython notification
+
+
+Please note, there will be notification in the notification bar unless you explicitly close the console and you always can reach the open console by tapping the notification. 
+
+
+
+.. image:: ../_static/guide_howtostart_pic5.png
+   :alt: QPython editor
+
+
+The editor allows you obviously (hello Cap!) enter and modify text. Here you can develop your scripts, save them and execute. The editor supports Python syntax highlighting and shows line numbers (there is no ability to go to the line by number though). *(above picture)*
+
+When typing, you can easily control indentation level (which is critical for Python code) using two buttons on the toolbar (1). Next buttons on the toolbar are **Save** and **Save As** (2), then goes **Run** (3), **Undo**, **Search**, **Recent Files** and **Settings** buttons. Also there are two buttons on the top: **Open** and **New** (5).
+
+When saving, don't forget to add `.py` estension to the file name since the editor don't do it for you.
+
+3. Programs
+--------------------
+You can find the scripts or projects in My QPython. My QPython contains the scripts and Projects. 
+
+By long clicking on script or project, you have chance to create the shortcut for the script or project. Once you have created the shortcuts on desktop, you can directly run the script or project from desktop.
+
+
+**Scripts**
+Scripts : A single script. The scripts are in the  /sdcard/com.hipipal.qpyplus/scripts directory.
+If you want your script could be found in My QPython, please upload it to this directory.
+
+When you click the script, you can choose the following actions:
+
+- Run : Run the script
+- Open : Edit the script with built-in editor
+- Rename : Rename the script
+- Delete : Delete the script
+
+**Projects**
+Projects : A directory which should contain the main.py as the project's default launch script, and you can put other dependency 3rd libraries or resources in the same directory, if you want your project could be found in My QPython, please upload them into this directory.
+
+When you click on the project, you can choose the following actions:
+
+- Run : run the project
+- Open : use it to explore project's resources
+- Rename : Rename the project
+- Delete : Delete the project
+
+4. Libraries 
+--------------
+
+By installing 3rd libraries, you can extend your qpython's programming ability quickly. There are some ways to install libraries.
+
+**QPypi**
+
+You can install some pre-built libraries from QPypi, like numpy etc.
+
+**Pip console**
+
+You can install most pure python libraries through pip console.
+
+
+Besides the two ways above, you could copy libraries into the /sdcard/qpython/lib/python2.7/site-packages in your device.
+
+
+*Notice:*
+Some libraries mixed with c/c++ files could not be install through pip console for the android lacks the compiler environment, you could ask help from qpython developer team.
+
+
+5. Community
+--------------
+It will redirect to the QPython.org, including somthe source of this documentation, and there are some qpython user communities' link, many questions of qpython usage or programming could be asked in the community.
+
+
+
+
+`Thanks dmych offer the first draft in his blog <http://onetimeblog.logdown.com/posts/2014/01/22/qpython-how-to-start>`_
+
+
+

docs/_sources/index.txt

@@ -76,7 +76,7 @@ Now, let's GO
 .. toctree::
    :maxdepth: 2
 
-   en/howtostart
+   en/guide
 
 For Chinese users
 ---------------

docs/en/callqpyapiinapp.html

@@ -33,7 +33,7 @@
 
 
     <link rel="top" title="QPython 0.9 documentation" href="../index.html"/>
-        <link rel="up" title="QPython Getting started" href="howtostart.html"/>
+        <link rel="up" title="QPython Getting started" href="guide.html"/>
         <link rel="next" title="How to submit the documentation" href="contributorshowto.html"/>
         <link rel="prev" title="Python builtin Libraries" href="sl4aapis.html"/> 
 
@@ -89,8 +89,8 @@
 
 
               <ul class="current">
-<li class="toctree-l1"><a class="reference internal" href="howtostart.html">QPython Getting started</a></li>
-<li class="toctree-l1 current"><a class="reference internal" href="howtostart.html#programming-guide">Programming Guide</a><ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="guide.html">QPython Getting started</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="guide.html#programming-guide">Programming Guide</a><ul class="current">
 <li class="toctree-l2"><a class="reference internal" href="qpyprograms.html">What unique work can QPython do?</a></li>
 <li class="toctree-l2"><a class="reference internal" href="qeditor4web.html">Are there more efficient way for developing?</a></li>
 <li class="toctree-l2"><a class="reference internal" href="sl4aapis.html">Python builtin Libraries</a></li>
@@ -104,8 +104,8 @@
 <li class="toctree-l2"><a class="reference internal" href="#how-to-build-an-independt-apk-from-qpython-scripts">How to build an independt APK from QPython scripts?</a></li>
 </ul>
 </li>
-<li class="toctree-l1"><a class="reference internal" href="howtostart.html#qpython-hackers-guide">QPython Hackers&#8217; Guide</a></li>
-<li class="toctree-l1"><a class="reference internal" href="howtostart.html#contributors-guide">Contributors&#8217; Guide</a></li>
+<li class="toctree-l1"><a class="reference internal" href="guide.html#qpython-hackers-guide">QPython Hackers&#8217; Guide</a></li>
+<li class="toctree-l1"><a class="reference internal" href="guide.html#contributors-guide">Contributors&#8217; Guide</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../zhindex.html">中文用户向导</a></li>
@@ -153,7 +153,7 @@
 
       <li><a href="../index.html">Docs</a> &raquo;</li>
 
-          <li><a href="howtostart.html">QPython Getting started</a> &raquo;</li>
+          <li><a href="guide.html">QPython Getting started</a> &raquo;</li>
 
       <li>How to call QPython script in your application?</li>
 

docs/en/contributorshowto.html

@@ -33,7 +33,7 @@
 
 
     <link rel="top" title="QPython 0.9 documentation" href="../index.html"/>
-        <link rel="up" title="QPython Getting started" href="howtostart.html"/>
+        <link rel="up" title="QPython Getting started" href="guide.html"/>
         <link rel="next" title="中文用户向导" href="../zhindex.html"/>
         <link rel="prev" title="How to call QPython script in your application?" href="callqpyapiinapp.html"/> 
 
@@ -89,10 +89,10 @@
 
 
               <ul class="current">
-<li class="toctree-l1"><a class="reference internal" href="howtostart.html">QPython Getting started</a></li>
-<li class="toctree-l1"><a class="reference internal" href="howtostart.html#programming-guide">Programming Guide</a></li>
-<li class="toctree-l1"><a class="reference internal" href="howtostart.html#qpython-hackers-guide">QPython Hackers&#8217; Guide</a></li>
-<li class="toctree-l1 current"><a class="reference internal" href="howtostart.html#contributors-guide">Contributors&#8217; Guide</a><ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="guide.html">QPython Getting started</a></li>
+<li class="toctree-l1"><a class="reference internal" href="guide.html#programming-guide">Programming Guide</a></li>
+<li class="toctree-l1"><a class="reference internal" href="guide.html#qpython-hackers-guide">QPython Hackers&#8217; Guide</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="guide.html#contributors-guide">Contributors&#8217; Guide</a><ul class="current">
 <li class="toctree-l2 current"><a class="current reference internal" href="#">How to submit the documentation</a></li>
 </ul>
 </li>
@@ -143,7 +143,7 @@
 
       <li><a href="../index.html">Docs</a> &raquo;</li>
 
-          <li><a href="howtostart.html">QPython Getting started</a> &raquo;</li>
+          <li><a href="guide.html">QPython Getting started</a> &raquo;</li>
 
       <li>How to submit the documentation</li>