Skip to content

Commit

Permalink
Make doc structure consistent and up-to-date (kivy#1750)
Browse files Browse the repository at this point in the history
* 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:
* Documentation version number now fetched from `buildozer/__init__.py`. Addresses kivy#1738
* Implemented many/all of the formatting changes from kivy#1708.
* Copy-edit of documents.
   * Contents of Contributing.rst moved to CONTRIBUTING.md
   * Removed installation intructions from README.md, so there is only one
     version.
   * Added Recipes description to RST documentation
   * Removed broken index page

CHECKLIST

* CONTRIBUTING.md
   [x] If repo takes user contributions, is present
   [x] In root dir (not .github dir)
   [x] Explains relationship to Kivy, if unclear.
   [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
   [x] If repo is big enough for RST documentation, is present.

* README:
   [x] Is a Markdown file.
   [x Describes the project.
   [x] Describes its place in the Kivy sibling projects.
   [x] If Documentation exists, mention it.
   [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, including:
        [x] Backers
		[x] Sponsors
		[x] GitHub contributors
		[x] Contributor Covenant
		[x] PyPI Version
		[x] PyPI Python Version
		[x] Build/Test status

   [x] Displays all contributors to the repo.
   [x] Displays backers
   [x] Displays top sponsors.

* RST documentation, if present
   [x] Describes the project.
   [x] Describes its place in the Kivy sibling projects.
   [x] Mentions (Kivy/Kivy) Contact Us link.
   [x] Mentions LICENSE.
   [x] Mentions CONTRIBUTING
   [x] Mentions FAQ
   [x] conf.py mentioned Kivy Team and other contributors
		- copyright, latex_documents, man_pages, texinfo documents

* 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 repo's CONTACT.md

* setup.py/cfg, if present and on PyPI
   [x] Supplies description to PyPI
   [x] Supplies Python versions to PyPI
   [x] Supplies Documentation, if any, to PyPI

* Buildozer.io is a broken link

* Update docs/source/installation.rst

Co-authored-by: Mirko Galimberti <me@mirkogalimberti.com>

---------

Co-authored-by: Mirko Galimberti <me@mirkogalimberti.com>
  • Loading branch information
Julian-O and misl6 authored Dec 4, 2023
1 parent 937a076 commit 6fcea49
Show file tree
Hide file tree
Showing 15 changed files with 415 additions and 211 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/support.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ jobs:
action:
runs-on: ubuntu-latest
steps:
- uses: dessant/support-requests@v3
- uses: dessant/support-requests@v4
with:
github-token: ${{ github.token }}
support-label: 'support'
Expand Down
8 changes: 8 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -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).

6 changes: 6 additions & 0 deletions CONTACT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Contacting the Kivy Team

If you are looking to contact the Kivy Team (who are responsible for managing
the Buildozer project), including looking for support, please see our
latest [Contact Us](https://github.com/kivy/kivy/blob/master/CONTACT.md)
document.
67 changes: 67 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Contribution Guidelines

Buildozer is part of the [Kivy](https://kivy.org) ecosystem - a large group of
products 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
[Contribution Guidelines](https://github.com/kivy/kivy/blob/master/CONTRIBUTING.md)
for general guidelines of how you can help us.

---

If you would like to work on Buildozer, you can set up a development build:
```bash
git clone https://github.com/kivy/buildozer
cd buildozer
python setup.py build
pip install -e .
```
---

Buildozer uses python-for-android, that is architected to be extensible with
new recipes and new bootstraps.

If you do develop a new recipe on python-for-android, here is how to test it:

#. Fork `Python for Android <https://github.com/kivy/python-for-android>`_, and
clone your own version (this will allow easy contribution later)::

```bash
git clone https://github.com/YOURNAME/python-for-android
```

#. Change your `buildozer.spec` to reference your version::

p4a.source_dir = /path/to/your/python-for-android

#. Copy your recipe into `python-for-android/recipes/YOURLIB/recipe.sh`

#. Rebuild.

When your recipe works, you can ask us to
include it in the python-for-android project, by issuing a Pull Request:

#. Create a branch::

```bash
git checkout --track -b recipe-YOURLIB origin/master
```

#. Add and commit::

```bash
git add python-for-android/recipes/YOURLIB/*
git commit -am 'Add support for YOURLIB`
```
#. Push to GitHub
```bash
git push origin master
```
#. Go to `https://github.com/YOURNAME/python-for-android`, and you should see
your new branch and a button "Pull Request" on it. Use it, write a
description about what you did, and Send!
31 changes: 31 additions & 0 deletions FAQ.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# FAQ for Buildozer

## Introduction

Buildozer is a development tool for turning [Python](https://www.python.org/)
applications into binary packages ready for installation on any of a number of
platforms, including mobile devices.

The app developer provides a single "buildozer.spec" file, which describes the
application's requirements and settings, such as title and icons. Buildozer can
then create installable packages for Android, iOS, Windows, macOS and/or Linux.

Buildozer is managed by the [Kivy Team](https://kivy.org/about.html). It relies
on its sibling projects:
[python-for-android](https://github.com/kivy/python-for-android/) and
[Kivy for iOS](https://github.com/kivy/kivy-ios/). It has features to make
building apps using the [Kivy framework](https://github.com/kivy/kivy) easier,
but it can be used independently - even with other GUI frameworks.

## How do I write my own recipes?

Instructions on how to write your own recipes is available in the
[Kivy for iOS](https://github.com/kivy/kivy-ios/) and
[python-for-android documentation](https://python-for-android.readthedocs.io/en/latest/recipes/).

Instructions on how to test your own recipes from Buildozer is available in the
[Buildozer Contribution Guidelines](CONTRIBUTING.md).

> [!NOTE]
> This document is very short at the moment. Please contribute some FAQ
> questions and answers.
Loading

0 comments on commit 6fcea49

Please sign in to comment.