diff --git a/doc/sources/contribute.rst b/doc/sources/contribute.rst index 56aa66c74..f1c93642a 100644 --- a/doc/sources/contribute.rst +++ b/doc/sources/contribute.rst @@ -30,7 +30,7 @@ Reporting an Issue ------------------ If you found anything wrong, a crash, segfault, missing documentation, invalid -spelling, weird example, please take 2 minutes to report the issue. +spelling or just weird examples, please take 2 minutes to report the issue. #. Move your logging level to debug by editing `/.kivy/config.ini`:: @@ -40,13 +40,13 @@ spelling, weird example, please take 2 minutes to report the issue. #. Execute again your code, and copy/paste the complete output to http://gist.github.com/, including the log from Kivy and the python backtrace. #. Open https://github.com/kivy/kivy/issues/ -#. Write a title of your issue -#. Explain how we can do to reproduce the issue + paste the link of the output previously sent on pocoo -#. Validate the issue, you're done ! +#. Write the title of your issue +#. Explain exactly what do to reproduce the issue + paste the link of the output posted on http://gist.github.com/ +#. Validate the issue and you're done ! -If you feel good, you can also try to resolve the bug, and contribute by sending us -the patch :) Read the next section about how to do it. +If you are feeling up to it, you can also try to resolve the bug, and contribute by sending +us the patch :) Read the next section to find out how to do this. Code Contributions ------------------ @@ -62,24 +62,24 @@ code history (you can opt-out if you don't want that). Coding style ~~~~~~~~~~~~ -- If you didn't do it yet, read the +- If you haven't done it yet, read the `PEP8 `_ about coding style in python. -- Activate pep8 check on git commit like this:: +- Activate the pep8 check on git commits like this:: make hook -This will pass the code added to git staging zone (about to be committed) -thought a pep8 checker program when you do a commit, and check that you didn't -introduce pep8 errors, if so, the commit will be rejected, correct the errors, -and try again. +This will pass the code added to the git staging zone (about to be committed) +thought a pep8 checker program when you do a commit, and ensure that you didn't +introduce pep8 errors. If you did, the commit will be rejected: please correct the +errors and try again. -Performances -~~~~~~~~~~~~ +Performance +~~~~~~~~~~~ -- take care of performance issues, read +- take care of performance issues: read `Python performance tips `_ -- cpu intensive parts of Kivy are written in cython, if you are doing a lot of +- cpu intensive parts of Kivy are written in cython: if you are doing a lot of computation, consider using it too. Git & GitHub @@ -97,7 +97,7 @@ however, is well beyond the scope of this document. Also, we use `GitHub `_ to host our code. In the following we will assume that you have a (free) GitHub account. While this part is optional, it allows for a tight integration between your patches and our upstream code -base. If you don't want to use GitHub, we assume you know what you do anyway. +base. If you don't want to use GitHub, we assume you know what you are doing anyway. Code Workflow ~~~~~~~~~~~~~ @@ -105,7 +105,7 @@ Code Workflow So here is the initial setup to begin with our workflow (you only need to do this once to install Kivy). Basically you follow the installation instructions from :ref:`dev-install`, but you don't clone our repository, -but the fork you create with the following steps: +you fork it. Here are the steps: #. Log in to GitHub #. Create a fork of the `Kivy repository `_ by @@ -118,7 +118,7 @@ but the fork you create with the following steps: clone. This will run our styleguide check whenever you do a commit, and if there are violations in the parts that you changed, your commit will be aborted. Fix & retry. - #. Add kivy repo as a remote source:: + #. Add the kivy repo as a remote source:: git remote add kivy https://github.com/kivy/kivy.git @@ -142,9 +142,9 @@ Now, whenever you want to create a patch, you follow the following steps: creating one commit per line changed. Use ``git add -p`` if necessary. #. Give each commit an appropriate commit message, so that others who are not familiar with the matter get a good idea of what you changed. - #. Once you are satisfied with your changes, merge with our upstream - repository. We can pull your stuff, but since you know best what you - changed, you should do the merge:: + #. Once you are satisfied with your changes, pull our upstream repository and + merge it with you local repository. We can pull your stuff, but since you know + exactly what's changed, you should do the merge:: git pull kivy master @@ -175,7 +175,8 @@ get instant karma. Congratulations, you're a hero! Documentation Contributions --------------------------- -Documentation contributions generally follow the same workflow as code contributions, just a bit more lax. +Documentation contributions generally follow the same workflow as code contributions, +but are just a bit more lax. #. Following the instructions above, @@ -193,12 +194,12 @@ Documentation contributions generally follow the same workflow as code contribut To submit a documentation update, use the following steps: - #. Create a new, appropriately named branch in your local repository.:: + #. Create a new, appropriately named branch in your local repository:: git checkout -b my_docs_update #. Modify the documentation with your correction or improvement. - #. Re-generate the HTML pages, and review your update.:: + #. Re-generate the HTML pages, and review your update:: make html @@ -216,11 +217,11 @@ We don't ask you to go through all the hassle just to correct a single typo, but Docstrings ~~~~~~~~~~ -Every module/class/method/function need a docstring, use the following keyword -when relevant +Every module/class/method/function needs a docstring, so use the following keywords +when relevant: -- ``.. versionadded::`` to mark the version the feature was added. -- ``.. versionchanged::`` to mark the version behaviour of the feature was +- ``.. versionadded::`` to mark the version in which the feature was added. +- ``.. versionchanged::`` to mark the version in which the behaviour of the feature was changed. - ``.. note::`` to add additional info about how to use the feature or related feature. @@ -263,7 +264,7 @@ When refering to other parts of the api use: - ``:doc:`api-kivy.module``` to refer to the documentation of a module (same for a class and a method) -Obviously replacing `module` `class` and `method` with their real name, and +Obviously replacing `module` `Class` and `method` with their real name, and using using '.' to separate modules refering to imbricated modules, e.g:: :mod:`~kivy.uix.floatlayout` @@ -278,8 +279,8 @@ Will result in: :meth:`~kivy.core.window.WindowBase.toggle_fullscreen` :doc:`/api-kivy.core.window` -`:doc:` and `:mod:` are essentially the same, except for an anchor in the url, -this makes `:doc:` prefered, for the cleaner url. +`:doc:` and `:mod:` are essentially the same, except for an anchor in the url +which makes `:doc:` prefered for the cleaner url. To build your documentation, run:: @@ -289,13 +290,13 @@ If you updated your kivy install, and have some trouble compiling docs, run:: make clean force html -The doc will be generated in ``docs/build/html``. +The docs will be generated in ``docs/build/html``. Unit tests contributions ------------------------ -For testing team, we have the document :doc:`contribute-unittest` that -explain how Kivy unit test is working, and how you can create your own. Use the +For the testing team, we have the document :doc:`contribute-unittest` that +explains how Kivy unit tests work and how you can create your own. Use the same approach as the `Code Workflow` to submit new tests. .. toctree:: diff --git a/doc/sources/faq.rst b/doc/sources/faq.rst index e79b3bf59..4f27fa17b 100644 --- a/doc/sources/faq.rst +++ b/doc/sources/faq.rst @@ -14,8 +14,8 @@ Technical FAQ Fatal Python error: (pygame parachute) Segmentation Fault ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Most of time, this issue is due to an usage of old graphics driver. Install the -latest graphics driver available for your graphics card, and it could be ok. +Most of time, this issue is due to the usage of old graphics drivers. Install the +latest graphics driver available for your graphics card, and it should be ok. If not, this means you have probably triggered some OpenGL code without an available OpenGL context. If you are loading images, atlases, using graphics @@ -31,15 +31,15 @@ instructions, you must spawn a Window first:: If not, please report a detailed issue on github by following the instructions in the :ref:`reporting_issues` section of the :doc:`contribute` documentation. This is very important for us because that kind of error can be very hard -to debug. Give us all the informations you can give about your environment and +to debug. Give us all the information you can give about your environment and execution. undefined symbol: glGenerateMipmap ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You might have a too old graphics card. Update your graphics drivers to the -latest available version, and retry. +You graphics card or its drivers might be too old. Update your graphics drivers to the +latest available version and retry. ImportError: No module named event ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -52,9 +52,9 @@ using it. In the kivy directory, do:: Pip installation failed ~~~~~~~~~~~~~~~~~~~~~~~ -Installing Kivy using Pip is not currently supported. Because Pip force the -usage of setuptools, setuptools hack build_ext to use pyrex for generating .c, -and they are no clean solution to hack against both weird behaviors to use +Installing Kivy using Pip is not currently supported. Because Pip forces the +usage of setuptools, setuptools hacks build_ext to use pyrex for generating .c, +meaning there is no clean solution to hack against both weird behaviors to use Cython. (Reference: http://mail.scipy.org/pipermail/nipy-devel/2011-March/005709.html) Solution: use `easy_install`, as our documentation said. @@ -66,13 +66,13 @@ Android FAQ could not extract public data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This message error can happen in many cases. Ensure that: +This error message can occur under various circumstances. Ensure that: -* you have a phone with sdcard -* you are not currently in a "USB Mass Storage" mode -* you have the permissions to write on sdcard +* you have a phone with an sdcard +* you are not currently in "USB Mass Storage" mode +* you have permissions to write to the sdcard -In case of USB Mass Storage mode error, and if you don't want to keep +In the case of the "USB Mass Storage" mode error, and if you don't want to keep unplugging the device, set the usb option to Power. Crash on touch interaction on Android 2.3.x @@ -81,18 +81,18 @@ Crash on touch interaction on Android 2.3.x There have been reports of crashes on Adreno 200/205 based devices. Apps otherwise run fine but crash when interacted with/through the screen. -These reports also mentioned the issue being resolved when moving to a ICS or +These reports also mentioned the issue being resolved when moving to an ICS or higher rom. Is it possible to have a kiosk app on android 3.0 ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Thomas Hansen have wrote a detailed answer on kivy-users mailing list: +Thomas Hansen have wrote a detailed answer on the kivy-users mailing list: https://groups.google.com/d/msg/kivy-users/QKoCekAR1c0/yV-85Y_iAwoJ -Basicaly, you need to root de device, remove the SystemUI package, add some -line on the xml configuration, and you're done. +Basically, you need to root the device, remove the SystemUI package, add some +lines to the xml configuration, and you're done. Project FAQ @@ -104,7 +104,7 @@ Why do you use Python? Isn't it slow? Let us try to give a thorough answer; please bear with us. Python is a very agile language that allows you to do many things -in (by comparison) short time. +in a (by comparison) short time. For many development scenarios, we strongly prefer writing our application quickly in a high-level language such as Python, testing it, then optionally optimizing it. @@ -120,7 +120,7 @@ quite expensive and given that we often want to do that for rich user experiences, that would be a fair argument. **But**, in virtually every case your application ends up spending most of the time (by far) executing the same part of the code. -For Kivy for example, these parts are event dispatching and graphics +In Kivy, for example, these parts are event dispatching and graphics drawing. Now Python allows you to do something to make these parts much faster. @@ -128,17 +128,17 @@ By using Cython, you can compile your code down to the C level, and from there your usual C compiler optimizes things. This is a pretty pain free process and if you add some hints to your code, the result becomes even faster. We are talking about a speed up -in performance by a factor of anything in between 1x and up to more +in performance by a factor of anything between 1x and up to more than 1000x (greatly depends on your code). In Kivy, we did this for -you and implemented the portions of our code where efficiency really -is critical on the C level. +you and implemented the portions of our code, where efficiency really +is critical, on the C level. For graphics drawing, we also leverage today's GPUs which are, for some tasks such as graphics rasterization, much more efficent than a CPU. Kivy does as much as is reasonable on the GPU to maximize performance. If you use our Canvas API to do the drawing, there is even a compiler that we invented which optimizes your drawing code -automatically. If you keep your drawing on the GPU mostly, +automatically. If you keep your drawing mostly on the GPU, much of your program's execution speed is not determined by the programming language used, but by the graphics hardware you throw at it. @@ -151,8 +151,8 @@ But even if this is not sufficient, you still have the option of using Cython for your own code to *greatly* speed it up. Trust us when we say that we have given this very careful thought. -We have performed many different benchmarks and came up with quite -some clever optimizations to make your application run smoothly. +We have performed many different benchmarks and come up with some +clever optimizations to make your application run smoothly. Does Kivy support Python 3.x? @@ -161,11 +161,11 @@ Does Kivy support Python 3.x? No. Not yet. Python 3 is certainly a good thing; However, it broke backwards compatibility (for good reasons) which means that some considerable portion of available Python projects do not yet work -with Python 3. This also applies to some of the projects that Kivy can -use as a dependency, which is why we didn't make the switch yet. -We would also need to switch our own codebase to Python 3. We didn't -do that yet because it's not very high on our priority list, but if -somebody doesn't want to wait for us doing it, please go ahead. +with Python 3. This also applies to some of the projects that Kivy +uses as a dependency, which is why we haven't make the switch yet. +We would also need to switch our own codebase to Python 3. We haven't +done that yet because it's not very high on our priority list, but if +somebody doesn't want to wait for us to do it, please go ahead. Please note, though, that Python 2.x is still the de facto standard. @@ -177,23 +177,23 @@ area of expertise. However, before Kivy came around there was (and still is) a project named PyMT that was led by our core developers. We learned a great deal from that project during the time that we developed it. In the more than two years of research and development -we found many interesting ways on how to improve the design of our -framework. We have done numerous benchmarks and as it turns out, to -achieve the great speed and flexibility that Kivy has, we had to +we found many interesting ways to improve the design of our +framework. We have performed numerous benchmarks and as it turns out, +to achieve the great speed and flexibility that Kivy has, we had to rewrite quite a big portion of the codebase, making this a backwards-incompatible but future-proof decision. -Most notably are the performance increases, which are just incredible. -Kivy starts and operates just so much faster, due to heavy +Most notable are the performance increases, which are just incredible. +Kivy starts and operates just so much faster, due to these heavy optimizations. We also had the opportunity to work with businesses and associations using PyMT. We were able to test our product on a large diversity of -setups and made PyMT work on all of these. Writing a system such as -Kivy or PyMT is one thing. Making it work under all the different +setups and made PyMT work on all of them. Writing a system such as +Kivy or PyMT is one thing. Making it work under all these different conditions is another. We have a good background here, and brought our knowledge to Kivy. -Furthermore, since some of our core developers decided to stop their full-time -jobs and to turn to this project completely, it was decided that a more +Furthermore, since some of our core developers decided to drop their full-time +jobs and turn to this project completely, it was decided that a more professional foundation had to be laid. Kivy is that foundation. It is supposed to be a stable and professional product. Technically, Kivy is not really a successor to PyMT because there is @@ -209,9 +209,9 @@ Do you accept patches? ~~~~~~~~~~~~~~~~~~~~~~ Yes, we love patches. In order to ensure a smooth integration of your -precious changes, however, please make sure to read our contribution +precious changes however, please make sure to read our contribution guidelines. -Obviously we don't accept every patch. Your patch has to be coherent +Obviously we don't accept every patch. Your patch has to be consistent with our styleguide and, more importantly, make sense. It does make sense to talk to us before you come up with bigger changes, especially new features. @@ -220,7 +220,7 @@ changes, especially new features. Does the Kivy project participate in Google's Summer of Code ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Potential students ask whether we participate in GSOC. +Potential students ask whether we participate in GSoC. The clear answer is: Indeed. :-) If you want to participate as a student and want to maximize your @@ -238,7 +238,7 @@ Here's a checklist: * Do some research **yourself**. GSoC is not about us teaching you something and you getting paid for that. It is about you trying to achieve agreed upon goals by yourself with our support. The main driving force in this should be, - obviously, yourself, though. Many students come up and ask what they should + obviously, yourself. Many students come up and ask what they should do. Well, we don't know because we know neither your interests nor your skills. Show us you're serious about it and take initiative. * Write a draft proposal about what you want to do. Include what you understand @@ -249,7 +249,7 @@ Here's a checklist: If not, send an email and just wait. Most questions are already answered in the docs or somewhere else and can be found with some research. If your questions don't reflect that you've actually thought through what you're - asking, that might not be received well. + asking, it might not be well received. Good luck! :-)