-
Notifications
You must be signed in to change notification settings - Fork 9
/
index.html
442 lines (309 loc) · 25.9 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<title>Kivy Garden by kivy-garden</title>
<link rel="stylesheet" href="stylesheets/fresh.css">
<link rel="stylesheet" href="stylesheets/garden.css">
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body>
<div id="topbar">
<div id="topwrapper">
<div id="toplogo">
<a href="http://kivy.org/">
<img src="stylesheets/logo-kivy.png" alt="Kivy" height="50"/>
</a>
</div>
<div id="topmenu">
<ul class="navigation">
<li><a class="nav-guides" href="http://kivy.org/docs/gettingstarted/intro.html">Guides</a></li>
<li><a class="nav-garden current" href="http://kivy-garden.github.io">Garden</a></li>
<li><a class="nav-api" href="http://kivy.org/docs/api-kivy.html">API Reference</a></li>
<li><a class="nav-pdf" href="http://kivy.org/docs/pdf/Kivy-latest.pdf">PDF</a></li>
<li><a class="nav-wiki" href="http://wiki.kivy.org">Wiki</a></li>
</ul>
</div>
</div>
</div>
<div class="contentall">
<div class="sphinxsidebar" style="padding-left: 20px;">
<h3 class="sphinxsidebar">Kivy Garden</h3>
<ul class="sphinxsidebar">
<li><a href="index.html#generalusageguidelines">General Usage Guidelines</a></li>
<li><a href="index.html#developmentguidelines">Development Guidelines</a></li>
<li><a href="index.html#makingareleaseforyourflower">Making a release for your flower</a></li>
<li><a href="index.html#disablingnotificationspam">Disabling notification spam</a></li>
<li><a href="index.html#transferringrepository">Transferring repository</a></li>
<li><a href="index.html#legacygardentoolgeneralusageguidelines">Legacy Garden Tool General Usage Guidelines</a></li>
<li><a href="index.html#guideformigratingflowersfromlegacystructure">Guide for migrating flowers from legacy structure</a></li>
<li><a href="gallery.html">Gallery</a></li>
</ul>
</div>
<div class="flower">
<table cellspacing=10>
<tr>
<td>
<div class="floweremptysquare"></div>
</td>
<td>
<div class="flowersquare"></div>
</td>
<td>
<div class="floweremptysquare"></div>
</td>
</tr>
<tr>
<td>
<div class="flowersquare"></div>
</td>
<td>
<div class="floweremptysquare"></div>
</td>
<td>
<div class="flowersquare"></div>
</td>
</tr>
<tr>
<td>
<div class="floweremptysquare"></div>
</td>
<td>
<div class="flowersquare"></div>
</td>
<td>
<div class="floweremptysquare"></div>
</td>
</tr>
</table>
</div>
<div id="content">
<h1 id="welcometokivygarden">Welcome to Kivy Garden</h1>
<p>This is an organization for developers of Kivy widgets, add-ons and related software.</p>
<p>If you have a kivy flower you'd like to contribute to garden see <a href="#developinganewflower">Developing a new flower</a>.</p>
<p>Memberships are granted for users who have contributed to existing garden flowers in the past year or have submitted their own flower in the application. Please note that memberships expire after a year of inactivity.</p>
<p style="color:#FF0000">
The garden flower widgets are contributed by regular users such as yourself. The kivy developers do not take any responsibility for the code hosted in the garden organization repositories - we do not actively monitor the flower repos. Please use at your own risk.
</p>
<h2 id="updatetogardenstructure">Update to garden structure</h2>
<p>Starting with the kivy 1.11.0 release, kivy has <a href="https://github.com/kivy/kivy/wiki/Moving-kivy.garden.xxx-to-kivy_garden.xxx-and-kivy.deps.xxx-to-kivy_deps.xxx">shifted</a> from using the garden legacy tool that installs flowers with <code>garden install flower</code> and where the flower does not have a proper python package structure to flowers that can be installed with pip and uploaded to pypi. Kivy supports the legacy garden flowers side by side with the newer packages so the garden tool and legacy flowers will be able to be used indefinitely. But we will only provide support for the newer packages format in the future.</p>
<p>For garden package maintainers - for a guide how to migrate your garden package from the legacy structure <code>garden.flower</code> to the newer <code>flower</code> structure used with the pip, see <a href="#guideformigratingflowersfromlegacystructure">this guide</a>.</p>
<h2 id="generalusageguidelines">General Usage Guidelines</h2>
<p>To use a kivy garden flower, first check if the flower is in the legacy format. If the flower name is in the format of <code>garden.flower</code>, such as <a href="https://github.com/kivy-garden/garden.graph">garden.graph</a> it is a legacy flower. If it is just <code>flower</code> such as <a href="https://github.com/kivy-garden/graph">graph</a> it is in the present format. If it is in the legacy format see <a href="#legacygardentoolgeneralusageguidelines">Legacy Garden Tool General Usage Guidelines</a> for how to install and use it. Otherwise, continue with the guide below.</p>
<p>Garden flowers can be installed with the <code>pip</code> tool like a normal python package. Given a flower that you want to install, lets use <a href="https://github.com/kivy-garden/graph">graph</a> as an example. You can install it directly from github master with:</p>
<pre><code class="sh language-sh">python -m pip install https://github.com/kivy-garden/graph/archive/master.zip
</code></pre>
<p>Look under the repository's releases tab if you'd like to install a specific release or a pre-compiled wheel, if the flower has any. Then use the url with <code>pip</code>.</p>
<p>Or you can automatically install it using garden's pypi server with:</p>
<pre><code class="sh language-sh">python -m pip install kivy_garden.graph --extra-index-url https://kivy-garden.github.io/simple/
</code></pre>
<p>To permanently add our garden server to your pip configuration so that you don't have to specify it with <code>--extra-index-url</code>, add</p>
<pre><code class="yaml language-yaml">[global]
timeout = 60
index-url = https://kivy-garden.github.io/simple/
</code></pre>
<p>to your <a href="https://pip.pypa.io/en/stable/user_guide/#config-file">pip.conf</a>.</p>
<p>If the flower maintainer has uploaded the flower to <a href="https://pypi.org/">pypi</a>, you can just install it with <code>pip install kivy_garden.flower</code>.</p>
<h1 id="developmentguidelines">Development Guidelines</h1>
<h2 id="developinganewflower">Developing a new flower</h2>
<p>If your flower will be a pure python flower start with the pure python <a href="https://github.com/kivy-garden/flower">demo</a>. If it is a cython flower, start with this <a href="https://github.com/kivy-garden/cython_flower">demo</a>.</p>
<ol>
<li><p>Create a new empty repository in your github account named <code>widgetname</code> (the lowercase name of the widget you're contributing).</p></li>
<li><p>Clone the demo repo locally (the following instructions use git ssh urls, replace <code>[email protected]:your_github_username</code> with <code>https://github.com/your_github_username</code> if you don't have <code>ssh</code> set up):</p>
<pre><code class="sh language-sh">git clone [email protected]:kivy-garden/flower.git widgetname
</code></pre>
<p>or if will be a cython flower:</p>
<pre><code class="sh language-sh">git clone [email protected]:kivy-garden/cython_flower.git widgetname
</code></pre>
<p>You'll be modifying the demo flower to contain your own widget.</p></li>
<li><p>Now mirror the demo to your account and fix the git origin to point to your account:
<code>sh
cd widgetname
git push --mirror [email protected]:your_github_username/widgetname.git
git remote set-url origin [email protected]:your_github_username/widgetname.git
</code></p></li>
<li><p>Start customizing the demo repo for your flower:</p>
<p><ol>
<li>Rename the <code>kivy_garden/flower</code> directory to <code>kivy_garden/widgetname</code>.</li></p>
<p><li>Replace the contents of <code>kivy_garden/widgetname/__init__.py</code> with code for your widget. People will be importing your new widget with <code>from kivy_garden.widgetname import WidgetName</code> so make sure that works.</li></p>
<p><li>Fix the tests in <code>tests/</code> to test your widget. The test are run with pytest. Try to test as much as you can.</li></p>
<p><li>Fix the <code>README.md</code> with basic information about your widget.</li></p>
<p><li>Fix <code>setup.py</code> to replace all references of <code>flower</code> with <code>widgetname</code> and everything else as appropriate.</li></p>
<p><li>Test install it to python and use it in your app to see if it works:
<code>sh
pip install -e .
</code>
This installs it in place so you can test and change the source code directly without having to reinstall every time. To test:
<code>sh
python -c "from kivy_garden.widgetname import WidgetName"
</code>
If it's a cython flower, compile it after any changes:
<code>sh
python setup.py build_ext --inplace
</code>
To run the tests:
<code>sh
python -m pytest tests/
</code></li></p>
<p><li>If you enable travis integration for your new <code>widgetname</code> repo on github, the code will be automatically tested on travis after every commit (see the <code>.travis.yml</code> file - you shouldn't need to change anything there). Kivy-garden will automatically run travis integration on all flowers, so make sure it works.</li></p>
<p><li>Finally, add your changes, commit and push all your changes to github:
<code>sh
git push origin master
</code></li></p>
<p><li>Make sure that travis runs without failures, otherwise fix and push etc.</li></ol>
<p></p></li></p>
<p><li><p>Now that the <code>widgetname</code> repo is ready, you're ready to transfer it into kivy-garden. See <a href="#transferringrepository">Transferring repository</a>.</p></li></p>
<p><li><p>To make the project installable with <code>pip</code>, you'll need to add it to garden's simple pypi server.</p></p>
<p><ol>
<li>Fork the <a href="https://github.com/kivy-garden/kivy-garden.github.io">garden website</a> into your account.</li></p>
<p><li>Take a look at how the current flowers are <a href="https://github.com/kivy-garden/kivy-garden.github.io/tree/master/simple">listed</a> and add a similar new file for your flower (<code>kivy-garden-widgetname/index.html</code>).</li></p>
<p><li>Add your flower to the root <code>simple/index.html</code> file.</li></p>
<p><li>Make a pull request to the original <a href="https://github.com/kivy-garden/kivy-garden.github.io">repo</a> and link to it in your issue that requests that your flower be added to kivy-garden that you opened in <a href="#transferringrepository">Transferring repository</a>.</li></ol></p>
<p></li></p>
<p><li><p>In the future if you want tp make a release to your flower and change the version, see <a href="#Making a release for your flower">Making a release for your flower</a> for how to make a release and add these releases to the pypi server.</p></li>
</ol></p>
<h2 id="flowerguidelines">Flower guidelines</h2>
<ol>
<li><p>Code added to the garden <strong>must be licensed under MIT</strong> (same as Kivy) and a LICENSE file must be added to every repository.</p></li>
<li><p>Keep the Widget and add-on simple. <strong>Do one task and do it well</strong>.</p></li>
<li><p>Name your widget correctly. Don't put "Widget" in the widget name as this is obvious. (SliderWidget, ProgressBarWidget are wrong, keep it simple.)</p></li>
<li><p>Create adequate documentation that explains the functionality of your widget. A doc directory using sphinx documentation is adequate, or just nice docs in the actualy code or readme.</p></li>
<li><p>Follow the <a href="http://www.python.org/dev/peps/pep-0008/">PEP8 guidelines</a> for coding standards.</p></li>
<li><p>Follow the kivy <a href="http://kivy.org/docs/contribute.html">guidelines for contributing</a>. To install the pep8 checker into your git directory do</p>
<pre>cp path-to-kivy/kivy/tools/pep8checker/pre-commit.githook path-to-your-source/.git/hooks/pre-commit
chmod +x path-to-garden-source/.git/hooks/pre-commit</pre>
<p>Then assuming you have kivy in your path, our style guide check will run whenever you do a commit, and if there are violations in the parts that you changed, your commit will be aborted. Fix & retry.</p></li>
<li><p>Use the <a href="http://kivy.org/docs/api-kivy.modules.monitor.html"><code>Monitor</code> module</a> to ensure that your widget can maintain a FPS rate above 60, ensuring smooth interaction with the user.</p></li>
<li><p>Follow the <a href="http://wiki.python.org/moin/PythonSpeed/PerformanceTips">performance guidelines for Python</a>, like ensuring minimum lookups, avoiding lookups in loops...</p></li>
<li><p>As a way of self-organizing widgets, add a screenshot named "<code>screenshot.png</code>" to the root of your repo showcasing the widget.</p></li>
<li><p>Use tags instead of a directory structure to categorize your widgets in the documentation.</p></li>
</ol>
<p>Note: you must have a GitHub account to open a ticket. You can create one for free <a href="https://github.com/">here</a>.</p>
<h2 id="makingareleaseforyourflower">Making a release for your flower</h2>
<ol>
<li>Update <code>CHANGELOG.md</code> and commit the changes</li>
<li>Update <code>__version__</code> in <code>kivy-garden/flower/__init__.py</code> (or in <code>kivy-garden/flower/_version.py</code> if it's a cython flower) to the next version and commit the change. If it's <code>x.y.z.dev0</code>, remove the <code>dev0</code> to update to the release version.</li>
<li>Call <code>git tag -a x.y.z -m "Tagging version x.y.z"</code> to make a tag</li>
<li>Call <code>python setup.py bdist_wheel --universal</code> (or <code>python setup.py bdist_wheel</code> if it's a cython flower) and <code>python setup.py sdist</code>, which generates the wheel and sdist in the dist/* directory.</li>
<li>Make sure the dist directory contains the files to be uploaded to pypi and call <code>twine check dist/*</code></li>
<li>Then call <code>twine upload dist/*</code> to upload to pypi.</li>
<li>Call <code>git push origin master --tags</code> to push the latest changes and the tags to github.</li>
<li>In github, go to the release tab and draft a new release for the tag. Upload there any wheels you generated (if any).</li>
<li>Make a new PR that updates <code>https://github.com/kivy-garden/kivy-garden.github.io/blob/master/simple/kivy-garden-widgetname/index.html</code> to list any new wheels, sdist, and versions as needed. Link to the github release files as needed. See the <a href="https://kivy-garden.github.io/simple/">website</a> for information on how to list files on a pypi server.</li>
<li>Update <code>__version__</code> in <code>kivy-garden/flower/__init__.py</code> (or in <code>kivy-garden/flower/_version.py</code> if it's a cython flower) to the next dev (e.g. <code>x.y+1.z.dev0</code>) version and commit and push the change.</li>
</ol>
<h2 id="otherissues">Other issues</h2>
<p>For all other issues, please open a ticket in the appropriate <a href="https://github.com/kivy-garden">repository</a>.</p>
<h2 id="disablingnotificationspam">Disabling notification spam</h2>
<p>By default you are subscribed to all new Garden github repository notifications. Unless you disable this yourself, your inbox will soon contain only Github spam.</p>
<p>Go to <a href="https://github.com/watching">https://github.com/watching</a>
Select what to watch or uncheck Automatically watch. But attention: latter will disable watch for all organizations.</p>
<h2 id="transferringrepository">Transferring repository</h2>
<p>Once you have a flower repository ready and all the tests are passing, you're ready to transfer it to garden.</p>
<p>How to move your repository to Kivy Garden shared ownership?</p>
<p>About transferring the ownership of repositories. See Github instructions regarding transfers</p>
<p>Join us by opening a <a href="https://github.com/kivy-garden/kivy-garden.github.io/issues/new?title=Please%20add%20me%20to%20Kivy%20Garden&body=Link%20for%20a%20merged%20garden%20PR%20or%20a%20proposed%20new%20flower%3A%0A%3Cgarden%20PR%20or%20transferable%20repository%20link%3E">new issue</a> indicating you have a flower to contribute.</p>
<p>Request the github name of any of the Kivy Garden administrators team on the github issue who is ready to initiate the process. Make sure they are actually an admin. Then, make them the owner of the repository which needs to be transferred. If the repository is already part of Github organization then create a new team and make the garden admin person the sole member of this team. Then assign the ownership permission of the repository to the new team. Now the garden administrator can go to the repository settings and press Transfer Ownership button</p>
<h1 id="legacyflowers">Legacy Flowers</h1>
<h2 id="legacygardentoolgeneralusageguidelines">Legacy Garden Tool General Usage Guidelines</h2>
<ol>
<li><p>Make sure you have <code>requests</code> installed:</p>
<pre>sudo pip install requests</pre></li>
<li><p>Install <code>kivy-garden</code> if you don't have it:</p>
<pre>pip install kivy-garden</pre>
<p>Make sure you have the folder that contains <code>garden</code> file on your <code>PATH</code> (or <code>cd</code> to the folder).</p>
<pre>$ garden list</pre>
<p>To list all the installed garden packages</p>
<pre>$ garden search</pre>
<p>To search garden packages on GitHub</p>
<pre>$ garden install package_name</pre>
<p>To install a garden package</p>
<pre>$ garden uninstall package_name</pre>
<p>To uninstall a garden package</p></li>
<li><p>To use a installed garden package:</p>
<pre>from kivy.garden import package_name</pre></li>
<li><p>By default the installation is done in <code>~/.kivy/garden/garden.widgetname</code> so that all kivy apps can use the widget once installed.</p>
<p>To include the package in your mobile distribution, you should install the garden package with <code>--app</code> command line argument, this way the package is downloaded and installed in your app directory and thus included in your apk.</p>
<pre>cd my_app_dir
/path/to/kivy_instalation/kivy/tools/garden install --app graph</pre>
<p>This should install the Graph Widget in <code>my_app_dir/libs/garden/garden.widgetname</code></p></li>
</ol>
<h2 id="guideformigratingflowersfromlegacystructure">Guide for migrating flowers from legacy structure</h2>
<p>This is a guide for how to migrate a flower with legacy <code>garden.flower</code> structure to the new proper python package <code>flower</code> structure.</p>
<ul>
<li>Demo of the result of converting <strong>pure-python</strong> graph from <a href="https://github.com/kivy-garden/garden.graph">legacy</a> to <a href="https://github.com/kivy-garden/graph">updated</a>.</li>
<li>Demo of the result of converting <strong>cython-python</strong> collider from <a href="https://github.com/kivy-garden/garden.collider">legacy</a> to <a href="https://github.com/kivy-garden/collider">updated</a>.</li>
</ul>
<p>Here are the base <a href="https://github.com/kivy-garden/flower/">pure-python</a> and <a href="https://github.com/kivy-garden/cython_flower">cython-python</a> flowers to be used as starting points for the migration.</p>
<p>The following steps use the garden graph package to demonstrate how to migrate a package to the new format.</p>
<ol>
<li><p>Ensure that the original flower issues and pull requests are closed or can be closed because the repo will be archived after the following process. Issues can be transferred to the new repo if needed.</p></li>
<li><p>Create a new empty repo with the name <code>graph</code> in <a href="https://github.com/kivy-garden/">garden</a> or request in a new issue that we create one for you and give you access.</p></li>
<li><p>In <a href="https://coveralls.io">coveralls</a> sync the <code>kivy-garden</code> repos and then enable it (or request that we enable it).</p></li>
<li><p>Clone the flower demo repo, if you haven't already. Otherwise make sure it is up to date with master:
For a pure python flower:
<code>sh
git clone [email protected]:kivy-garden/flower.git
</code>
or for a cython-python flower:
<code>sh
git clone [email protected]:kivy-garden/cython_flower.git
</code></p></li>
<li><p>Push the flower repo to github:
<code>sh
cd flower
git push --mirror [email protected]:kivy-garden/graph.git
</code></p></li>
<li><p>Now clone <code>graph</code> and the original <code>garden.graph</code> locally:
<code>sh
git clone [email protected]:kivy-garden/graph.git
git clone [email protected]:kivy-garden/garden.graph.git
</code></p></li>
<li><p>Merge <code>garden.graph</code> into the new <code>graph</code>:</p>
<pre><code class="sh language-sh">cd graph
git remote add original ../garden.graph
git remote update
git merge --allow-unrelated-histories original/master
</code></pre>
<p>If there are any merge conflicts, resolve them and commit.</p></li>
<li><p>Migrate the original package structure into a pythonic structure.</p>
<p><ol>
<li>Remove the <code>kivy-garden/flower</code> directory and make a new <code>kivy-garden/graph</code> directory.</li></p>
<p><li>Copy all the original python modules e.g. <code>__init__.py</code> into <code>kivy-garden/graph</code>.</li></p>
<p><li>Fix the tests in <code>tests/</code> to test the graph code.</li></p>
<p><li>open <code>setup.py</code> and replace all instances of <code>flower</code> with <code>graph</code>.</li></p>
<p><li>Do any remaining cleanup, e.g. duplicate license files or readme.</li></p>
<p><li>Commit all changes.</li></ol>
<p></p></li></p>
<p><li><p>Test to make sure everything works, otherwise fix and commit (make sure <code>pytest</code> is installed).
Test install it to python and use it in your app:
<code>sh
pip install .
python -c "from kivy_garden.graph import Graph"
</code>
If it's a cython flower (graph isn't), compile it first:
<code>sh
PYTHONPATH=.:$PYTHONPATH python setup.py build_ext --inplace
</code>
Then run the tests:
<code>sh
PYTHONPATH=. python -m pytest tests/
</code></p></li></p>
<p><li><p>Push to kivy-garden and remove the original garden remote
<code>sh
git push origin master
git remote rm original
</code></p></li></p>
<p><li><p>Verify that the travis tests pass.</p></li></p>
<p><li><p>Transfer issues from the <code>garden.graph</code> to <code>graph</code> and archive <code>garden.graph</code>.</p></li>
</ol></p>
</div>
</div>
<script src="javascripts/scale.fix.js"></script>
</body>
</html>