From ee64c9674036cffcf5371e458de482856e2a9ce7 Mon Sep 17 00:00:00 2001 From: Julian-o Date: Sun, 26 Nov 2023 12:26:04 +1100 Subject: [PATCH] Make doc structure consistent and up-to-date This is part of an effort to make the Kivy sibling projects' documentation structure consistent and up-to-date. Unrelated fixes: * Mild copy-edit of README * Mention it only works on macOS CHECKLIST * CONTRIBUTING.md [x] If repo takes user contributions, is present [x] In root dir (not .github dir) [x] Refers to kivy/kivy Contribution Guidelines. * LICENSE [x] If repo takes user contributions, is present. [x] Acknowledges the range of years to 2023. [x] Acknowledges Kivy Team and other contributors [x] Mentions it is an MIT License. * CODE_OF_CONDUCT.md [x] If repo takes user contributions or hosts discussions, is present. [x] Refers to kivy/kivy CODE_OF_CONDUCT.md * CONTACT.md [x] Refers to kivy/kivy CONTACT.md * FAQ.md [NA] If repo is big enough for RST documentation, is present. ** Added anyway because it was bloating the README ** * README: [x] Is a Markdown file. [x] Describes the project. [x] Describes its place in the Kivy sibling projects. [x] If CONTRIBUTING exists, mentions it. [x] If LICENSE exists, mentions it. [x] If CODE_OF_CONDUCT exists, mentions it. [x] Mentions kivy/kivy CONTACT.md [NA] Uses Python syntax colouring for embedded Python code. [x] Uses badges to display current status. * RST documentation, if present [NA] Describes the project. [NA] Describes its place in the Kivy sibling projects. [NA] Mentions LICENSE. [NA] Mentions CONTRIBUTING [NA] Mentions CODE_OF_CONDUCT [NA] Mentions FAQ * WORKFLOWS [x] NO_RESPONSE.yml is present if the repo has awaiting_reply tag. [x] NO_RESPONSE uses latest script versions. [x] SUPPORT.yml is present if the repo has a `support` tag. [x] SUPPORT.yml refers to kivy/kivy CONTACT.md * setup.py/cfg, if present and on PyPI [x] Supplies description to PyPI [x] Supplies Python versions to PyPI [NA] Supplies Documentation, if any, to PyPI [x] Supplies GitHub link to PyPI --- .github/workflows/support.yml | 13 ++-- CODE_OF_CONDUCT.md | 8 +++ CONTACT.md | 8 +++ CONTRIBUTING.md | 11 +++ FAQ.md | 39 ++++++++++ LICENSE | 4 +- README.md | 131 +++++++++++++--------------------- setup.cfg | 19 ++++- 8 files changed, 142 insertions(+), 91 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTACT.md create mode 100644 CONTRIBUTING.md create mode 100644 FAQ.md diff --git a/.github/workflows/support.yml b/.github/workflows/support.yml index b832de81e..fec14fa7a 100644 --- a/.github/workflows/support.yml +++ b/.github/workflows/support.yml @@ -11,22 +11,21 @@ jobs: action: runs-on: ubuntu-latest steps: - - uses: dessant/support-requests@v2 + - uses: dessant/support-requests@v4 with: github-token: ${{ github.token }} support-label: 'support' issue-comment: > 👋 We use the issue tracker exclusively for bug reports and feature requests. However, this issue appears to be a support request. Please use our - [support channels](https://github.com/kivy/kivy-ios/blob/master/README.md#support) + [support channels](https://github.com/kivy/kivy/blob/master/README.md#support) to get help with the project. - - If you're having trouble installing or using kivy-ios, - maybe you could be interested to [installation and requirements](https://github.com/kivy/kivy-ios/blob/master/README.md#installation--requirements). - + For troubleshooting advice and other frequently asked questions, consult + the latest + [Kivy for iOS FAQ](https://github.com/kivy/kivy-ios/blob/master/FAQ.md). Let us know if this comment was made in error, and we'll be happy to reopen the issue. close-issue: true - lock-issue: false \ No newline at end of file + lock-issue: false diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..29d18faa2 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ +In the interest of fostering an open and welcoming community, we as +contributors and maintainers need to ensure participation in our project and +our sister projects is a harassment-free and positive experience for everyone. +It is vital that all interaction is conducted in a manner conveying respect, +open-mindedness and gratitude. + +Please consult the [latest Kivy Code of Conduct](https://github.com/kivy/kivy/blob/master/CODE_OF_CONDUCT.md). + diff --git a/CONTACT.md b/CONTACT.md new file mode 100644 index 000000000..337d75cc7 --- /dev/null +++ b/CONTACT.md @@ -0,0 +1,8 @@ +# Contacting the Kivy Team + +Are you having trouble using the Kivy framework, or any of its related projects? +Is there an error you don’t understand? Are you trying to figure out how to use +it? We have volunteers who can help! + +The best channels to contact us for support are listed in the latest +[Contact Us](https://github.com/kivy/kivy/blob/master/CONTACT.md) document. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..a0eccbf93 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,11 @@ +# Contribution Guidelines + +Kivy is a large product used by many thousands of developers for free, but it +is built entirely by the contributions of volunteers. We welcome (and rely on) +users who want to give back to the community by contributing to the project. + +Contributions can come in many forms. See the latest +[Kivy Contribution Guidelines](https://github.com/kivy/kivy/blob/master/CONTRIBUTING.md) +for how you can help us. + + diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 000000000..a318e42e2 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,39 @@ +# FAQ for Kivy for iOS + +## Introduction + +Kivy for iOS (kivy-ios) is a toolchain to compile the necessary libraries for +[iOS](https://www.apple.com/ios/) to run [Kivy](https://kivy.org) applications, +and manage the creation of [Xcode](https://developer.apple.com/xcode/) projects. + +## FAQ + +### Fatal error: "stdio.h" file not found + +You need to install the Command line tools: `xcode-select --install` + +### Error: SDK "iphonesimulator" cannot be located + +Xcode path is not set up correctly. Run the following command to fix this: `sudo xcode-select --switch ` (Change `` to the path that reflects your XCode installation, usually is `/Applications/Xcode.app`) + +### Bitcode is partially supported now (Xcode setting ENABLE_BITCODE can be set to Yes). + +* Supported recipes: python3, kivy, sdl2, sdl2_image, sdl2_mixer, and libffi + +### You don't have permissions to run + +It is due to invalid archs, search for them and check it. Maybe you +targetted a simulator but have only arm64. Maybe you want to target +your iPad but it is only x86_64. + +### Why does the python multiprocess/subprocess module not work? + +The iOS application model does not currently support multi-processing in a +cross-platform compatible way. The application design focuses on minimizing +processor usage (to minimize power consumption) and promotes an +[alternative concurrency model](https://developer.apple.com/library/archive/documentation/General/Conceptual/ConcurrencyProgrammingGuide/Introduction/Introduction.html). + +If you need to make use of multiple processes, you should consider using +[PyObjus](https://github.com/kivy/pyobjus) to leverage native iOS +functionals for this. + diff --git a/LICENSE b/LICENSE index d5d6b13c8..4e3506010 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,6 @@ -Copyright (c) 2010-2017 Kivy Team and other contributors +MIT License + +Copyright (c) 2010-2023 Kivy Team and other contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 8a318b064..94a0a4f9e 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,32 @@ # Kivy for iOS -[![kivy-ios](https://github.com/kivy/kivy-ios/workflows/kivy-ios/badge.svg)](https://github.com/kivy/kivy-ios/actions?query=workflow%3Akivy-ios) -[![PyPI version](https://badge.fury.io/py/kivy-ios.svg)](https://badge.fury.io/py/kivy-ios) -[![Backers on Open Collective](https://opencollective.com/kivy/backers/badge.svg)](#backers) -[![Sponsors on Open Collective](https://opencollective.com/kivy/sponsors/badge.svg)](#sponsors) -This toolchain is designed to compile the necessary libraries for iOS to run -your application and manage the creation of the Xcode project. +[![Backers on Open Collective](https://opencollective.com/kivy/backers/badge.svg)](https://opencollective.com/kivy) +[![Sponsors on Open Collective](https://opencollective.com/kivy/sponsors/badge.svg)](https://opencollective.com/kivy) +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md) -We do not provide any binary distributions of this toolchain. -You do need to compile it at least once before creating your Xcode project. +![PyPI - Version](https://img.shields.io/pypi/v/kivy-ios) +![PyPI - Python Version](https://img.shields.io/pypi/pyversions/kivy-ios) + +[![kivy-ios](https://github.com/kivy/kivy-ios/workflows/kivy-ios/badge.svg)](https://github.com/kivy/kivy-ios/actions?query=workflow%3Akivy-ios) + +Kivy for iOS (kivy-ios) is a toolchain to compile the necessary libraries for +[iOS](https://www.apple.com/ios/) to run [Kivy](https://kivy.org) applications, +and manage the creation of [Xcode](https://developer.apple.com/xcode/) projects. The toolchain supports: -- iPhone Simulator (x86_64) - iPhone / iOS (arm64) +- iPhone Simulator (x86_64) -These recipes are not ported to the new toolchain yet: +We do not provide any binary distributions of this toolchain. +You do need to compile it at least once before creating your Xcode project. -- lxml +Because Xcode only runs on macOS, Kivy for iOS is only useful on this +platform. +Kivy for iOS is managed by the [Kivy Team](https://kivy.org/about.html) and can be +used with [Buildozer](https://github.com/kivy/buildozer). ## Installation & requirements @@ -88,6 +95,10 @@ You can list the available recipes and their versions with: sdl2_ttf 2.0.12 werkzeug 1.0.1 +Note: These recipes are not ported to the new toolchain yet: + +- lxml + Then, start the compilation with: $ toolchain build python3 kivy @@ -109,8 +120,8 @@ These may, in turn, depend on others e.g. sdl2_ttf depends on freetype, etc. You can think of it as follows: the kivy recipe will compile everything necessary for a minimal working version of Kivy. -Don't grab a coffee, just do dinner. Compiling all the libraries for the first -time, 2x over (remember, 2 archs, x86_64, arm64) will take time. +Don't just grab a coffee; do dinner. Compiling all the libraries for the first +time, twice over (Remember: two architectures - x86_64, arm64) will take time. For a complete list of available commands, type: @@ -240,87 +251,43 @@ Then use the `toolchain.py` script: python toolchain.py --help - ## FAQ -### Fatal error: "stdio.h" file not found - -You need to install the Command line tools: `xcode-select --install` - -### Error: SDK "iphonesimulator" cannot be located - -Xcode path is not set up correctly. Run the following command to fix this: `sudo xcode-select --switch ` (Change `` to the path that reflects your XCode installation, usually is `/Applications/Xcode.app`) +For troubleshooting advice and other frequently asked questions, consult +the latest +[Kivy for iOS FAQ](https://github.com/kivy/kivy-ios/blob/master/FAQ.md). -### Bitcode is partially supported now (Xcode setting ENABLE_BITCODE can be set to Yes). - -* Supported recipes: python3, kivy, sdl2, sdl2_image, sdl2_mixer, and libffi - -### You don't have permissions to run - -It is due to invalid archs, search for them and check it. Maybe you -targetted a simulator but have only arm64. Maybe you want to target -your iPad but it is only x86_64. - -### Why does the python multiprocess/subprocess module not work? - -The iOS application model does not currently support multi-processing in a -cross-platform compatible way. The application design focuses on minimizing -processor usage (to minimize power consumption) and promotes an -[alternative concurrency model](https://developer.apple.com/library/archive/documentation/General/Conceptual/ConcurrencyProgrammingGuide/Introduction/Introduction.html). +## License -If you need to make use of multiple processes, you should consider using -[PyObjus](https://github.com/kivy/pyobjus) to leverage native iOS -functionals for this. +Kivy for iOS is [MIT licensed](LICENSE), actively developed by a great +community and is supported by many projects managed by the +[Kivy Organization](https://www.kivy.org/about.html). ## Support -If you need help, please feel free to seek assistance through our support channels: - -Join the [Kivy Users Google Group](https://groups.google.com/group/kivy-users). -Participate in discussions on [Discord](https://chat.kivy.org). +Are you having trouble using the Kivy framework, or any of its related projects? +Is there an error you don’t understand? Are you trying to figure out how to use +it? We have volunteers who can help! +The best channels to contact us for support are listed in the latest +[Contact Us](https://github.com/kivy/kivy/blob/master/CONTACT.md) document. ## Contributing -We love pull requests and discussing novel ideas. Check out our -[contribution guide](http://kivy.org/docs/contribute.html) and -feel free to improve Kivy for iOS. - -The following mailing list and IRC channel are used exclusively for -discussions about developing the Kivy framework and its sister projects: - -* Dev Group : https://groups.google.com/group/kivy-dev -* Email : kivy-dev@googlegroups.com - -Discord channel: - -* Server : https://chat.kivy.org -* Channel : #dev - -## License - -Kivy for iOS is released under the terms of the MIT License. Please refer to the -LICENSE file. - - -## Backers - -Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/kivy#backer)] - - +Kivy is a large product used by many thousands of developers for free, but it +is built entirely by the contributions of volunteers. We welcome (and rely on) +users who want to give back to the community by contributing to the project. +Contributions can come in many forms. See the latest +[Kivy Contribution Guidelines](https://github.com/kivy/kivy/blob/master/CONTRIBUTING.md) +for how you can help us. -## Sponsors +## Code of Conduct -Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/kivy#sponsor)] +In the interest of fostering an open and welcoming community, we as +contributors and maintainers need to ensure participation in our project and +our sister projects is a harassment-free and positive experience for everyone. +It is vital that all interaction is conducted in a manner conveying respect, +open-mindedness and gratitude. - - - - - - - - - - +Please consult the [latest Kivy Code of Conduct](https://github.com/kivy/kivy/blob/master/CODE_OF_CONDUCT.md). \ No newline at end of file diff --git a/setup.cfg b/setup.cfg index 16f725fbe..e7d2d69c6 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,13 +1,30 @@ [metadata] name = kivy-ios version = 2023.08.24 -description = Kivy for iOS +description = A toolchain to compile the necessary libraries for iOS to run Kivy applications. license = MIT License long_description = file: README.md long_description_content_type = text/markdown author = The Kivy team author_email = kivy-dev@googlegroups.com url = https://github.com/kivy/kivy-ios +classifiers = + Development Status :: 5 - Production/Stable + Intended Audience :: Developers + Topic :: Software Development :: Build Tools + Programming Language :: Python :: 3 + Programming Language :: Python :: 3.6 + Programming Language :: Python :: 3.7 + Programming Language :: Python :: 3.8 + Programming Language :: Python :: 3.9 + Programming Language :: Python :: 3.10 + Programming Language :: Python :: 3.11 + Programming Language :: Python :: 3.12 + Operating System :: MacOS :: MacOS X + Operating System :: iOS +project_urls = + Source=https://github.com/kivy/kivy-ios + Bug Reports=https://github.com/kivy/kivy-ios/issues [options] python_requires >= "3.6.0"