Make doc structure consistent and up-to-date (#703)

* 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. Extra items: * Fix capitalisation of PyJNIus throughout. * Standardize on tag line. * Remove "shell" from "shell environment variables" * Remove some Python 2-only code. 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 [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 CONTRIBUTING exists, mentions it. [x] If LICENSE exists, mentions it. [x] If CODE_OF_CONDUCT exists, mentions it. [x] Mentions kivy/kivy CONTACT.md [x] 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 [x] Mentions CODE_OF_CONDUCT [x] 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 [x] SYPPORT.yml uses dessant/support-requests@v4 * 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 * Update with review comments Tweaked SVG sizes. Made warning use Markdown syntax for warnings. Remove links overriding SVG for backers. Remove kivy/kivy contributors, and link to pyJNIus ones. Include the horrid links to sponsors, and link to why. Added badge for GitHub contributors to this project (in contrast to OpenCollective contributors to Kivy) Updated checklist * CONTRIBUTING.md [] If repo takes user contributions, is present [] In root dir (not .github dir) [] Explains relationship to Kivy, if unclear. [] Refers to kivy/kivy Contribution Guidelines. * LICENSE [] If repo takes user contributions, is present. [] Acknowledges the range of years to 2023. [] Acknowledges Kivy Team and other contributors [] Mentions it is an MIT License. * CODE_OF_CONDUCT.md [] If repo takes user contributions or hosts discussions, is present. [] Refers to kivy/kivy CODE_OF_CONDUCT.md * CONTACT.md [] Refers to kivy/kivy CONTACT.md * FAQ.md [] If repo is big enough for RST documentation, is present. * README: [] Is a Markdown file. [] Describes the project. [] Describes its place in the Kivy sibling projects. [] If Documentation exists, mention it. [] If CONTRIBUTING exists, mentions it. [] If LICENSE exists, mentions it. [] If CODE_OF_CONDUCT exists, mentions it. [] Mentions kivy/kivy CONTACT.md [] Uses Python syntax colouring for embedded Python code. [] Uses badges to display current status, including: [] Backers [] Sponsors [] GitHub contributors [] Contributor Covenant [] PyPI Version [] PyPI Python Version [] Build/Test status [] Links to GitHub contributors [] Displays backers in suitable icon size, without buttons. [] Displays first 40 sponsors icons and links * RST documentation, if present [] Describes the project. [] Describes its place in the Kivy sibling projects. [] Mentions (Kivy/Kivy) Contact Us link. [] Mentions LICENSE. [] Mentions CONTRIBUTING [] Mentions FAQ [] conf.py mentioned Kivy Team and other contributors - copyright, latex_documents, man_pages, texinfo documents * WORKFLOWS [] NO_RESPONSE.yml is present if the repo has awaiting_reply tag. [] NO_RESPONSE uses latest script versions. [] SUPPORT.yml is present if the repo has a `support` tag. [] SUPPORT.yml refers to repo's CONTACT.md * setup.py/cfg, if present and on PyPI [] Supplies description to PyPI [] Supplies Python versions to PyPI [] Supplies Documentation, if any, to PyPI * Improve links to sponsors, backers and contributors See https://github.com/orgs/kivy/discussions/15 for context. * Correct contributor URL Co-authored-by: Mirko Galimberti <me@mirkogalimberti.com> --------- Co-authored-by: Mirko Galimberti <me@mirkogalimberti.com>
kivy · Dec 3, 2023 · dce5ce0 · dce5ce0
1 parent a2c799f
commit dce5ce0
Show file tree

Hide file tree

Showing 18 changed files with 228 additions and 88 deletions.
diff --git a/.github/workflows/support.yml b/.github/workflows/support.yml
@@ -11,16 +11,16 @@ 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/pyjnius/blob/master/README.md#support)
+            [support channels](https://github.com/kivy/pyjnius/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

diff --git a/CODE_OF_CONDUCT.md 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
@@ -0,0 +1,6 @@
+# Contacting the Kivy Team
+
+If you are looking to contact the Kivy Team (who are responsible for managing
+the PyJNIus project), including looking for support, please see our
+latest [Contact Us](https://github.com/kivy/kivy/blob/master/CONTACT.md) 
+document.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,10 @@
+# Contribution Guidelines
+
+PyJNIus 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.
diff --git a/FAQ.md b/FAQ.md
@@ -0,0 +1,15 @@
+# FAQ for PyJNIus
+
+## Introduction
+
+PyJNIus is a [Python](https://www.python.org/) library for accessing 
+[Java](https://www.java.com/) classes using the 
+[Java Native Interface](https://docs.oracle.com/javase/8/docs/technotes/guides/jni/)
+(JNI). 
+
+Warning: the [PyPI](https://pypi.org/) package name is now 
+[pyjnius](https://pypi.org/project/pyjnius/) instead of `jnius`.
+
+## No questions yet
+
+No Frequently Asked Questions have been identified yet. Please contribute some.
diff --git a/LICENSE b/LICENSE
@@ -1,4 +1,6 @@
-Copyright (c) 2010-2020 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
@@ -1,16 +1,33 @@
 PyJNIus
 =======
 
-A Python module to access Java classes as Python classes using the Java Native
-Interface (JNI).
-Warning: the pypi name is now `pyjnius` instead of `jnius`.
+PyJNIus is a [Python](https://www.python.org/) library for accessing 
+[Java](https://www.java.com/) classes using the 
+[Java Native Interface](https://docs.oracle.com/javase/8/docs/technotes/guides/jni/)
+(JNI). 
+
+PyJNIus is managed by the [Kivy Team](https://kivy.org/about.html) and can be
+used with [python-for-android](https://github.com/kivy/python-for-android). 
+
+It can also be used independently of Kivy, on desktop and mobile platforms. 
+
+> [!WARNING]
+> The [PyPI](https://pypi.org/) package name is now 
+[pyjnius](https://pypi.org/project/pyjnius/) instead of `jnius`.
+
+
+[![Backers on Open Collective](https://opencollective.com/kivy/backers/badge.svg)](#backers)
+[![Sponsors on Open Collective](https://opencollective.com/kivy/sponsors/badge.svg)](#sponsors)
+[![GitHub contributors](https://img.shields.io/github/contributors-anon/kivy/pyjnius)](https://github.com/kivy/pyjnius/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/pyjnius)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyjnius)
 
 [![Tests](https://github.com/kivy/pyjnius/workflows/Continuous%20Integration/badge.svg)](https://github.com/kivy/pyjnius/actions)
 [![Tests (x86)](https://github.com/kivy/pyjnius/workflows/Continuous%20Integration%20(x86)/badge.svg)](https://github.com/kivy/pyjnius/actions)
 [![Builds](https://github.com/kivy/pyjnius/workflows/Continuous%20Delivery/badge.svg)](https://github.com/kivy/pyjnius/actions)
-[![PyPI](https://img.shields.io/pypi/v/pyjnius.svg)]()
-[![Backers on Open Collective](https://opencollective.com/kivy/backers/badge.svg)](#backers)
-[![Sponsors on Open Collective](https://opencollective.com/kivy/sponsors/badge.svg)](#sponsors)
+
 
 Installation
 ------------
@@ -23,18 +40,18 @@ Quick overview
 --------------
 
 ```python
->>> from jnius import autoclass
->>> autoclass('java.lang.System').out.println('Hello world')
-Hello world
-
->>> Stack = autoclass('java.util.Stack')
->>> stack = Stack()
->>> stack.push('hello')
->>> stack.push('world')
->>> print(stack.pop())
-world
->>> print(stack.pop())
-hello
+    >>> from jnius import autoclass
+    >>> autoclass('java.lang.System').out.println('Hello world')
+    Hello world
+    
+    >>> Stack = autoclass('java.util.Stack')
+    >>> stack = Stack()
+    >>> stack.push('hello')
+    >>> stack.push('world')
+    >>> print(stack.pop())
+    world
+    >>> print(stack.pop())
+    hello
 ```
 
 Usage with python-for-android
@@ -43,7 +60,7 @@ Usage with python-for-android
 * Get [python-for-android](http://github.com/kivy/python-for-android)
 * Compile a distribution with kivy (PyJNIus will be automatically added)
 
-Then, you can do this kind of things:
+Then, you can do this kind of thing:
 
 ```python
 from time import sleep
@@ -53,9 +70,9 @@ Hardware = autoclass('org.renpy.android.Hardware')
 print('DPI is', Hardware.getDPI())
 
 Hardware.accelerometerEnable(True)
-for x in xrange(20):
+for x in range(20):
     print(Hardware.accelerometerReading())
-    sleep(.1)
+    sleep(0.1)
 ```
 
 It will output something like:
@@ -109,9 +126,9 @@ class Hardware(JavaClass):
 print('DPI is', Hardware.getDPI())
 
 Hardware.accelerometerEnable()
-for x in xrange(20):
+for x in range(20):
     print(Hardware.accelerometerReading())
-    sleep(.1)
+    sleep(0.1)
 ```
 
 You can use the `signatures` method of `JavaMethod` and `JavaMultipleMethod`, to inspect the discovered signatures of a method of an object
@@ -132,61 +149,94 @@ Make sure a Java Development Kit (JDK) is installed on your operating system if
 you want to use PyJNIus on desktop. OpenJDK is known to work, and the Oracle
 Java JDK should work as well.
 
-On windows, make sure `JAVA_HOME` points to your java installation, so PyJNIus
-can locate the `jvm.dll` file allowing it to start java. This shouldn't be
-necessary on OSX and Linux, but in case PyJNIus fails to find it, setting
+On Windows, make sure `JAVA_HOME` points to your Java installation, so PyJNIus
+can locate the `jvm.dll` file allowing it to start Java. This shouldn't be
+necessary on macOS and Linux, but in case PyJNIus fails to find it, setting
 `JAVA_HOME` should help.
 
-Support
--------
+## License
 
-If you need assistance, you can ask for help on our mailing list:
+PyJNIus 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).
 
-* User Group : https://groups.google.com/group/kivy-users
-* Email      : kivy-users@googlegroups.com
+## Documentation
 
-We also have a Discord server:
+[Documentation for this repository](https://pyjnius.readthedocs.io/).
 
-[https://chat.kivy.org/](https://chat.kivy.org/)
+## Support
 
-Contributing
-------------
+Are you having trouble using PyJNIus 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!
 
-We love pull requests and discussing novel ideas. Check out our
-[contribution guide](http://kivy.org/docs/contribute.html) and
-feel free to improve PyJNIus.
+The best channels to contact us for support are listed in the latest 
+[Contact Us](https://github.com/kivy/pyjnius/blob/master/CONTACT.md) document.
 
-The following mailing list and IRC channel are used exclusively for
-discussions about developing the Kivy framework and its sister projects:
+## Contributing
 
-* Dev Group : https://groups.google.com/group/kivy-dev
-* Email     : kivy-dev@googlegroups.com
+PyJNIus 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.
 
-License
--------
+Contributions can come in many forms. See the latest 
+[Contribution Guidelines](https://github.com/kivy/pyjnius/blob/master/CONTRIBUTING.md)
+for how you can help us.
 
-PyJNIus is released under the terms of the MIT License. Please refer to the
-LICENSE file for more information.
+## Code of Conduct
 
+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.
 
-## Backers
+Please consult the [latest Code of Conduct](https://github.com/kivy/pyjnius/blob/master/CODE_OF_CONDUCT.md).
+
+## Contributors
+
+This project exists thanks to 
+[all the people who contribute](https://github.com/kivy/pyjnius/graphs/contributors).
+[[Become a contributor](CONTRIBUTING.md)].
+
+<img src="https://contrib.nn.ci/api?repo=kivy/pyjnius&pages=5&no_bot=true&radius=22&cols=18">
 
-Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/kivy#backer)]
+## Backers
 
-<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>
diff --git a/docs/source/android.rst b/docs/source/android.rst
@@ -4,7 +4,7 @@ Android
 =======
 
 Android has a great and extensive API to control devices, your application
-etc. Some parts of the Android API are directly accessible with Pyjnius but
+etc. Some parts of the Android API are directly accessible with PyJNIus but
 some of them require you to code in Java.
 
 .. note::
@@ -37,7 +37,7 @@ Recording an audio file
 By looking at the `Audio Capture
 <http://developer.android.com/guide/topics/media/audio-capture.html>`_ guide
 for Android, you can see the simple steps for recording an audio file.
-Let's do it with Pyjnius::
+Let's do it with PyJNIus::
 
     from jnius import autoclass
     from time import sleep
@@ -97,7 +97,7 @@ Accessing the Activity
 
 This example will show how to start a new Intent. Be careful: some Intents
 require you to setup parts in the `AndroidManifest.xml` and have some
-actions performed within your Activity. This is out of the scope of Pyjnius but
+actions performed within your Activity. This is out of the scope of PyJNIus but
 we'll show you what the best approach is for playing with it.
 
 Using the Python-for-android project, you can access the default
@@ -131,7 +131,7 @@ Accelerometer access
 --------------------
 
 The accelerometer is a good example that shows how to write a little
-Java code that you can access later with Pyjnius.
+Java code that you can access later with PyJNIus.
 
 The `SensorManager
 <http://developer.android.com/reference/android/hardware/SensorManager.html>`_
@@ -188,7 +188,7 @@ everything needed for accessing the accelerometer::
 
 So we created one method named `accelerometerEnable` to activate/deactivate the
 listener. And we saved the last event received in `Hardware.lastEvent`.
-Now you can use it in Pyjnius::
+Now you can use it in PyJNIus::
 
     from time import sleep
     from jnius import autoclass
@@ -226,7 +226,8 @@ Using TextToSpeech
 ------------------
 
 Same as the audio capture, by looking at the `An introduction to Text-To-Speech in Android
-<http://android-developers.blogspot.fr/2009/09/introduction-to-text-to-speech-in.html>`_ blog post, it's easy to do it with Pyjnius::
+<http://android-developers.blogspot.fr/2009/09/introduction-to-text-to-speech-in.html>`_ blog post, it's easy to do it
+with PyJNIus::
 
     from jnius import autoclass
     Locale = autoclass('java.util.Locale')

diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -6,7 +6,7 @@ API
 
 .. module:: jnius
 
-This part of the documentation covers all the interfaces of Pyjnius.
+This part of the documentation covers all the interfaces of PyJNIus.
 
 Reflection classes
 ------------------
@@ -407,13 +407,13 @@ called from another Java method, the other Java method would see the value chang
 parameters are passed by reference. The two methods share the same memory space. Only one copy of
 the array data exists.
 
-In Pyjnius, Python calls to Java methods simulate pass by reference by copying the variable values
+In PyJNIus, Python calls to Java methods simulate pass by reference by copying the variable values
 from the JVM back to Python. This extra copying will have a performance impact for large data
 structures. To skip the extra copy and pass by value, use the named parameter `pass_by_reference`.
 
     obj.method(param1, param2, param3, pass_by_reference=False)
 
-Since Java does not have function named parameters like Python does, they are interpreted by Pyjnius
+Since Java does not have function named parameters like Python does, they are interpreted by PyJNIus
 and are not passed to the Java method.
 
 In the above example, the `pass_by_reference` parameter will apply to all the parameters. For more
@@ -442,17 +442,17 @@ If no classpath is provided and CLASSPATH is not set, the path defaults to `'.'`
 This functionality is not available on Android.
 
 
-Pyjnius and threads
+PyJNIus and threads
 -------------------
 
 .. function:: detach()
 
-    Each time you create a native thread in Python and use Pyjnius, any call to
-    Pyjnius methods will force attachment of the native thread to the current JVM.
-    But you must detach it before leaving the thread, and Pyjnius cannot do it for
+    Each time you create a native thread in Python and use PyJNIus, any call to
+    PyJNIus methods will force attachment of the native thread to the current JVM.
+    But you must detach it before leaving the thread, and PyJNIus cannot do it for
     you.
 
-Pyjnius automatically calls this `detach()` function for you when a python thread exits. This is done by
+PyJNIus automatically calls this `detach()` function for you when a python thread exits. This is done by
 monkey-patching the default `run()` method of `threading.Thread` class.
 
 So if you entirely override `run()` from your own subclass of Thread, you must call `detach()` yourself