Skip to content

Commit

Permalink
Make doc structure consistent and up-to-date (#786)
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 changes:
* Readme Copy-edit. Reformat markdown table
* RST added structure, including API page
* Congrats, promoted from "beta" to "stable" in setup classifiers

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.
   (RST documentation exists but is trivial)

* 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
   [x] Describes the project.
   [x] Describes its place in the Kivy sibling projects.
   [x] Mentions LICENSE.
   [x] Mentions CONTRIBUTING
   [NA] 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 kivy/kivy 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

* PEP8 fixes

Fixed some I am reasponsible for (setup and conf), and some I am not responsible for (space before line continuation)
but did not fix all I wasn't responsible for.

* Updated according to new checklist

Includes adding FAQ.

This is part of an effort to make the Kivy sibling projects' documentation
structure consistent and up-to-date.

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

* Review comments

* PEP8

Was bitten by PEP's 79 versus 80 width.
Decided to fix one more style-failure-that-wasn't-my-fault while I was here - redid the imports on garden.graph.

(Bring on `black`!)
  • Loading branch information
Julian-O authored Dec 7, 2023
1 parent 8c0e11f commit fee1bb2
Show file tree
Hide file tree
Showing 17 changed files with 277 additions and 110 deletions.
27 changes: 27 additions & 0 deletions .github/workflows/support.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
name: 'Support Requests'

on:
issues:
types: [labeled, unlabeled, reopened]

permissions:
issues: write

jobs:
action:
runs-on: ubuntu-latest
steps:
- 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/plyer/blob/master/CONTACT.md)
to get help with the project.
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
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).

8 changes: 8 additions & 0 deletions CONTACT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
.. _contact:

Contact Us
==========

If you are looking to contact the Kivy Team (who are responsible for managing the
Plyer project), including looking for support, please see our
`latest contact details <https://github.com/kivy/kivy/blob/master/CONTACT.md>`_.
10 changes: 10 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Contribution Guidelines

Plyer 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 how you can help us.
13 changes: 13 additions & 0 deletions FAQ.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# FAQ for Plyer

## Introduction

Plyer is a platform-independent Python API for accessing hardware features
of various platforms (Android, iOS, macOS, Linux and Windows).

Plyer is managed by the [Kivy Team](https://kivy.org/about.html). It is suitable for
use with Kivy apps, but can be used independently.

## No questions yet

No Frequently Asked Questions have been identified yet. Please contribute some.
4 changes: 3 additions & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -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
Expand Down
197 changes: 117 additions & 80 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,134 +1,171 @@
# Plyer

Plyer is a platform-independent api to use features commonly found on various
platforms, notably mobile ones, in Python.
Plyer is a platform-independent Python API for accessing hardware features
of various platforms (Android, iOS, macOS, Linux and Windows).

Plyer is managed by the [Kivy Team](https://kivy.org/about.html). It is suitable for
use with Kivy apps, but can be used independently.

[![coverage](https://coveralls.io/repos/kivy/plyer/badge.svg?branch=master)](https://coveralls.io/r/kivy/plyer?branch=master)
[![Backers on Open Collective](https://opencollective.com/kivy/backers/badge.svg)](#backers)
[![Sponsors on Open Collective](https://opencollective.com/kivy/sponsors/badge.svg)](#sponsors)
![Continuous Integration with Ubuntu](https://github.com/kivy/plyer/workflows/Continuous%20Integration%20with%20Ubuntu/badge.svg)
[![GitHub contributors](https://img.shields.io/github/contributors-anon/kivy/plyer)](https://github.com/kivy/plyer/graphs/contributors)
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md)


![PyPI - Version](https://img.shields.io/pypi/v/plyer)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/plyer)


[![coverage](https://coveralls.io/repos/kivy/plyer/badge.svg?branch=master)](https://coveralls.io/r/kivy/plyer?branch=master)
![Continuous Integration with Ubuntu](https://github.com/kivy/plyer/workflows/Continuous%20Integration%20with%20Ubuntu/badge.svg)
![Continuous Integration with OSX](https://github.com/kivy/plyer/workflows/Continuous%20Integration%20with%20OSX/badge.svg)
![Continuous Integration with Windows](https://github.com/kivy/plyer/workflows/Continuous%20Integration%20with%20Windows/badge.svg)
![Deploy to PyPI](https://github.com/kivy/plyer/workflows/Deploy%20to%20PyPI/badge.svg)


## How plyer works?

Plyer tries not to reinvent the wheel, and will call for external libraries to
implement the api in the easiest way, depending on the current platform.
Plyer tries not to reinvent the wheel, and will call external libraries to
implement the API in the easiest way, depending on the current platform.

- On Android(python-for-android), pyjnius is used
- On iOS(kivy-ios), pyobjus is used
- On windows/mac/linux, commonly found libraries and programs will be used
- On Android ([python-for-android](https://python-for-android.readthedocs.io/)), [PyJNIus](https://pypi.org/project/pyjnius/) is used.
- On iOS ([kivy-ios](https://pypi.org/project/kivy-ios/)) and macOS,
[pyobjus](https://pypi.org/project/pyobjus/) is used.
- On Windows, macOS and Linux, other commonly found libraries and programs
are used.


## Supported APIs

| Platform | Android | iOS | Windows | OS X | Linux |
| ------------------------------ | ------- | --- | ------- | ---- | ----- |
| Accelerometer ||| |||
| Audio recording || ||| |
| Barometer ||| | | |
| Battery ||||||
| Bluetooth || | || |
| Brightness ||| | ||
| Call ||| | | |
| Camera (taking picture) ||| | | |
| Compass ||| | | |
| CPU count | | ||||
| Devicename || ||||
| Email (open mail client) ||||||
| Flash ||| | | |
| GPS ||| | | |
| Gravity ||| | | |
| Gyroscope ||| | | |
| Humidity || | | | |
| IR Blaster || | | | |
| Keystore ||||||
| Light || | | | |
| Maps | || || |
| Native file chooser ||||||
| Notifications || ||||
| Orientation || | | ||
| Proximity || | | | |
| Screenshot | | ||||
| SMS (send messages) ||| || |
| Spatial Orientation ||| | | |
| Speech to text || | | | |
| Storage Path ||||||
| Temperature || | | | |
| Text to speech ||||||
| Unique ID ||||||
| Vibrator ||| | | |
| Wifi | | ||||

| Platform | Android | iOS | Windows | macOS | Linux |
| ------------------------------ |:-------:|:---:|:-------:|:-----:|:-----:|
| Accelerometer ||| |||
| Audio recording || ||| |
| Barometer ||| | | |
| Battery ||||||
| Bluetooth || | || |
| Brightness ||| | ||
| Call ||| | | |
| Camera (taking picture) ||| | | |
| Compass ||| | | |
| CPU count | | ||||
| Devicename || ||||
| Email (open mail client) ||||||
| Flash ||| | | |
| GPS ||| | | |
| Gravity ||| | | |
| Gyroscope ||| | | |
| Humidity || | | | |
| IR Blaster || | | | |
| Keystore ||||||
| Light || | | | |
| Maps | || || |
| Native file chooser ||||||
| Notifications || ||||
| Orientation || | | ||
| Proximity || | | | |
| Screenshot | | ||||
| SMS (send messages) ||| || |
| Spatial Orientation ||| | | |
| Speech to text || | | | |
| Storage Path ||||||
| Temperature || | | | |
| Text to speech ||||||
| Unique ID ||||||
| Vibrator ||| | | |
| Wifi | | ||||

## Documentation

Full documentation, including details about the API, is available
[online](https://plyer.readthedocs.io/en/latest/). If you are not using the
latest version of Plyer, earlier versions of the documentations are linked
from there.

## Installation

To use on desktop: `pip install plyer`
To use in python-for-android/kivy-ios: add `plyer` to your requirements if needed.

## Support
To use in python-for-android and Kivy for iOS, add `plyer` to your requirements
if needed.

If you need assistance, you can ask for help on our mailing list:
## License

* User Group : https://groups.google.com/group/kivy-users
* Email : kivy-users@googlegroups.com
Plyer 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).

Discord channel:
## Support

* Server : https://chat.kivy.org
* Channel : #dev
Are you having trouble using Plyer or any of its related projects in the Kivy
ecosystem?
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/plyer/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 Plyer.

The following mailing list and IRC channel are used exclusively for
discussions about developing the Kivy framework and its sister projects:
Plyer 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.

* Dev Group : https://groups.google.com/group/kivy-dev
* Email : kivy-dev@googlegroups.com
Contributions can come in many forms. See the latest
[Contribution Guidelines](https://github.com/kivy/plyer/blob/master/CONTRIBUTING.md)
for how you can help us.

IRC channel:
## Code of Conduct

* Server : irc.freenode.net
* Port : 6667, 6697 (SSL only)
* Channel : #kivy-dev


## License
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.

Plyer is released under the terms of the MIT License. Please refer to the
LICENSE file.
Please consult the [latest Code of Conduct](https://github.com/kivy/plyer/blob/master/CODE_OF_CONDUCT.md).

## Contributors

This project exists thanks to all the people who contribute. [[Contribute](http://kivy.org/docs/contribute.html)].
This project exists thanks to
[all the people who contribute](https://github.com/kivy/plyer/graphs/contributors).
[[Become a contributor](CONTRIBUTING.md)].

<a href="https://github.com/kivy/plyer/graphs/contributors"><img src="https://contrib.rocks/image?repo=kivy/plyer"/></a>
<img src="https://contrib.nn.ci/api?repo=kivy/plyer&pages=5&no_bot=true&radius=22&cols=18">

## Backers

Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/kivy#backer)]

<a href="https://opencollective.com/kivy#backers" target="_blank"><img src="https://opencollective.com/kivy/backers.svg?width=890"></a>
Thank you to [all of our backers](https://opencollective.com/kivy)!
🙏 [[Become a backer](https://opencollective.com/kivy#backer)]

<img src="https://opencollective.com/kivy/backers.svg?width=890&avatarHeight=44&button=false">

## Sponsors

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)]
Special thanks to
[all of our sponsors, past and present](https://opencollective.com/kivy).
Support this project by
[[becoming a sponsor](https://opencollective.com/kivy#sponsor)].

Here are our top current sponsors. Please click through to see their websites,
and support them as they support us.

<!--- See https://github.com/orgs/kivy/discussions/15 for explanation of this code. -->
<a href="https://opencollective.com/kivy/sponsor/0/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/1/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/2/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/3/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/3/avatar.svg"></a>

<a href="https://opencollective.com/kivy/sponsor/4/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/5/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/6/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/7/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/7/avatar.svg"></a>

<a href="https://opencollective.com/kivy/sponsor/8/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/9/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/9/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/10/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/10/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/11/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/11/avatar.svg"></a>

<a href="https://opencollective.com/kivy/sponsor/12/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/12/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/13/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/13/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/14/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/14/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/15/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/15/avatar.svg"></a>
11 changes: 11 additions & 0 deletions docs/source/api.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@

.. _api:

API
===

.. automodule:: plyer
:members:

.. automodule:: plyer.facades
:members:
13 changes: 8 additions & 5 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@

# General information about the project.
project = u'Plyer'
copyright = u'2013, Mathieu Virbel, Akshay Aurora, Gabriel Petier, Ben Rousch'
copyright = u'2013-2023, Kivy Team and other contributors'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
Expand Down Expand Up @@ -189,7 +189,7 @@
# (source start file, target name, title, author, documentclass [howto/manual])
latex_documents = [(
'index', 'Plyer.tex', u'Plyer Documentation',
u'Mathieu Virbel, Akshay Aurora, Gabriel Petier, Ben Rousch', 'manual'
u'Kivy Team and other contributors', 'manual'
), ]

# The name of an image file (relative to this directory) to place at the top of
Expand Down Expand Up @@ -219,7 +219,7 @@
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'plyer', u'Plyer Documentation',
[u'Mathieu Virbel, Akshay Aurora, Gabriel Petier, Ben Rousch'], 1)
[u'Kivy Team and other contributors'], 1)
]

# If true, show URL addresses after external links.
Expand All @@ -233,8 +233,11 @@
# dir menu entry, description, category)
texinfo_documents = [(
'index', 'Plyer', u'Plyer Documentation',
u'Mathieu Virbel, Akshay Aurora, Gabriel Petier, Ben Rousch',
'Plyer', 'One line description of project.', 'Miscellaneous'
u'Kivy Team and other contributors',
'Plyer',
'Plyer is a platform-independent Python API for accessing hardware '
'features of various platforms (Android, iOS, macOS, Linux and Windows).',
'Miscellaneous'
), ]

# Documents to append as an appendix to all manuals.
Expand Down
Loading

0 comments on commit fee1bb2

Please sign in to comment.