mirror of https://github.com/kivy/kivy.git
Small corrections and improvements to the documentaion
This commit is contained in:
Zen-CODE
parent
63c043b418
commit
befe5611a9
|
|
@ -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 `<user_directory>/.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 <http://www.python.org/dev/peps/pep-0008/>`_ 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 <http://wiki.python.org/moin/PythonSpeed/PerformanceTips>`_
|
||||
- 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 <http://github.com>`_ 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 <https://github.com/kivy/kivy>`_ 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::
|
||||
|
|
|
|||
|
|
@ -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! :-)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue