Splitting GraalPy documentation for JVM and Python audiences

Co-authored-by: Betty Mann <betty.mann@oracle.com>

Author: ban-mi

README.md

@@ -16,7 +16,7 @@ GraalPy is ready for production running pure Python code and has experimental su
 **Low-overhead integration with Java and other languages**
 
 * Use [Python in Java](docs/user/Interoperability.md) applications on GraalVM JDK, Oracle JDK, or OpenJDK
-* Use JVM tools like [Maven](docs/user/README.md), JFR, or [GraalVM Native Image](docs/user/Native-Images-with-Python.md)
+* Use JVM tools like [Maven](docs/user/Embedding-Build-Tools.md), JFR, or [GraalVM Native Image](docs/user/Native-Images-with-Python.md)
 * Manage Python libraries' system access thanks to GraalPy's [Java-based emulation of Python OS APIs](docs/user/Embedding-Permissions.md)
 
 **Compatible with the Python ecosystem**
@@ -84,65 +84,13 @@ This means that build tools have to be available and installation will take long
 We provide [Github actions](scripts/wheelbuilder) to help you build binary packages with the correct dependencies.
 Thanks to our integration with GraalVM Native Image, we can deploy Python applications as [standalone binary](docs/user/Python-Standalone-Applications.md), all dependencies included.
 
-* Linux
+**Quick Installation:**
 
-  The easiest way to install GraalPy on Linux is to use [Pyenv](https://github.com/pyenv/pyenv) (the Python version manager).
-  To install version 25.0.2 using Pyenv, run the following commands:
-  ```bash
-  pyenv install graalpy-25.0.2
-  ```
-  ```bash
-  pyenv shell graalpy-25.0.2
-  ```
-  > NOTE: There will be a delay between GraalPy release and its availability on Pyenv. Make sure to update Pyenv.
-
-  Alternatively, you can download a compressed GraalPy installation file from [GitHub releases](https://github.com/oracle/graalpython/releases).
-
-  1. Find the download that matches the pattern _graalpy-XX.Y.Z-linux-amd64.tar.gz_ or _graalpy-XX.Y.Z-linux-aarch64.tar.gz_ (depending on your platform) and download.
-  2. Uncompress the file and update your `PATH` environment variable to include the _graalpy-XX.Y.Z-linux-amd64/bin_ (or _graalpy-XX.Y.Z-linux-aarch64/bin_) directory.
-
-* macOS
-
-  The easiest way to install GraalPy on macOS is to use [Pyenv](https://github.com/pyenv/pyenv) (the Python version manager).
-  To install version 25.0.2 using Pyenv, run the following commands:
-  ```bash
-  pyenv install graalpy-25.0.2
-  ```
-  ```bash
-  pyenv shell graalpy-25.0.2
-  ```
-  > NOTE: There will be a delay between GraalPy release and its availability on Pyenv. Make sure to update Pyenv.
-
-  Alternatively, you can download a compressed GraalPy installation file from [GitHub releases](https://github.com/oracle/graalpython/releases).
-
-  1. Find the download that matches the pattern _graalpy-XX.Y.Z-macos-aarch64.tar.gz_ and download.
-  2. Remove the quarantine attribute.
-      ```bash
-      sudo xattr -r -d com.apple.quarantine /path/to/graalpy
-      ```
-      For example:
-      ```bash
-      sudo xattr -r -d com.apple.quarantine ~/.pyenv/versions/graalpy-25.0.2
-      ```
-  3. Uncompress the file and update your `PATH` environment variable to include to the _graalpy-XX.Y.Z-macos-aarch64/bin_ directory.
-
-* Windows
-
-  The Windows support of GraalPy is still experimental, so not all features and packages may be available.
-  The easiest way to install GraalPy on Windows is to use [Pyenv-win](https://pyenv-win.github.io/pyenv-win/) (the Python version manager for Windows).
-  To install version 25.0.2 using Pyenv-win, run the following commands:
-  ```cmd
-  pyenv install graalpy-25.0.2-windows-amd64
-  ```
-  ```cmd
-  pyenv shell graalpy-25.0.2-windows-amd64
-  ```
-  > NOTE: There will be a delay between GraalPy release and its availability on Pyenv. Make sure to update Pyenv.
-
-  Alternatively, you can download a compressed GraalPy installation file from [GitHub releases](https://github.com/oracle/graalpython/releases).
+- **Linux/macOS**: `pyenv install graalpy-25.0.2 && pyenv shell graalpy-25.0.2`
+- **Windows**: `pyenv install graalpy-25.0.2-windows-amd64`
+- **Manual**: Download from [GitHub releases](https://github.com/oracle/graalpython/releases)
 
-  1. Find the download that matches the pattern _graalpy-XX.Y.Z-windows-amd64.tar.gz_ and download.
-  2. Uncompress the file and update your `PATH` variable to include to the _graalpy-XX.Y.Z-windows-amd64/bin_ directory.
+**See the [complete installation guide](docs/user/Standalone-Getting-Started.md) for detailed instructions.**
 
 </details>
 <details>
@@ -161,36 +109,17 @@ The _setup-python_ action supports GraalPy:
 <details>
 <summary><strong><a name="start-migrating-jython-scripts-to-graalpy"></a>Migrating Jython Scripts to GraalPy</strong></summary>
 
-Most existing Jython code that uses Java integration will be based on a stable Jython release&mdash;however, these are only available in Python 2.x versions.
+Most existing Jython code that uses Java integration will be based on a stable Jython release—however, these are only available in Python 2.x versions.
 To migrate your code from Python 2 to Python 3, follow [the official guide from the Python community](https://docs.python.org/3/howto/pyporting.html).
 GraalPy provides a [special mode](docs/user/Python-on-JVM.md) to facilitate migration.
-To run Jython scripts, you need to use a GraalPy distribution running on the JVM so you can access Java classes from Python scripts.
-
-* Linux
-
-  1. Find and download a compressed GraalPy installation file from [GitHub releases](https://github.com/oracle/graalpython/releases) that matches the pattern _graalpy-jvm-XX.Y.Z-linux-amd64.tar.gz_ or _graalpy-jvm-XX.Y.Z-linux-aarch64.tar.gz_ (depending on your platform) and download.
-  2. Uncompress the file and update your `PATH` environment variable to include the _graalpy-jvm-XX.Y.Z-linux-amd64/bin_ (or _graalpy-jvm-XX.Y.Z-linux-aarch64/bin_) directory.
-  3. Run your scripts with `graalpy --python.EmulateJython`.
-
-* macOS
 
-  1. Find and download a compressed GraalPy installation file from [GitHub releases](https://github.com/oracle/graalpython/releases) that matches the pattern _graalpy-jvm-XX.Y.Z-macos-aarch64.tar.gz_ and download.
-  2. Remove the quarantine attribute.
-      ```bash
-      sudo xattr -r -d com.apple.quarantine /path/to/graalpy
-      ```
-      For example:
-      ```bash
-      sudo xattr -r -d com.apple.quarantine ~/.pyenv/versions/graalpy-25.0.2
-      ```
-  3. Uncompress the file and update your `PATH` environment variable to include to the _graalpy-jvm-XX.Y.Z-macos-aarch64/bin_ directory.
-  4. Run your scripts with `graalpy --python.EmulateJython`.
+**Quick Setup:**
 
-* Windows
+1. Download a GraalPy JVM distribution: `graalpy-jvm-XX.Y.Z-<platform>.tar.gz`
+2. Extract and add to PATH
+3. Run with: `graalpy --python.EmulateJython`
 
-  1. Find and download a compressed GraalPy installation file from [GitHub releases](https://github.com/oracle/graalpython/releases) that matches the pattern _graalpy-jvm-XX.Y.Z-windows-amd64.tar.gz_.
-  2. Uncompress the file and update your `PATH` variable to include to the _graalpy-jvm-XX.Y.Z-windows-amd64/bin_ directory.
-  3. Run your scripts with `graalpy --python.EmulateJython`.
+**See the [complete migration guide](docs/user/Python-on-JVM.md) for detailed instructions.**
 
 </details>
 

docs/site/01-docs.md

@@ -0,0 +1,38 @@
+---
+layout: docs
+title: Python Developers
+permalink: docs/python-developers/
+docs_index: python-developers
+nav_order: 1
+---
+
+# GraalPy for Python Developers
+
+**You want to use GraalPy instead of the standard Python from python.org.**
+
+Install GraalPy on your machine and use it like any Python interpreter.
+You get better performance, the ability to compile to native binaries, and access to the GraalVM ecosystem.
+
+{% gfm_docs ../user/Version-Compatibility.md %}
+
+{% gfm_docs ../user/Platform-Support.md %}
+
+These guides cover everything you need to know:
+
+{% gfm_docs ../user/Standalone-Getting-Started.md %}
+{% gfm_docs ../user/Python-Runtime.md %}
+{% gfm_docs ../user/Python-Standalone-Applications.md %}
+{% gfm_docs ../user/Native-Extensions.md %}
+{% gfm_docs ../user/Performance.md %}
+{% gfm_docs ../user/Tooling.md %}
+
+<h3 id="python-context-options">
+<a href="#python-context-options" class="anchor-link">Python Context Options</a>
+</h3>
+Below are the options you can set on contexts for GraalPy.
+{% python_options ../../graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonOptions.java %}
+
+{% gfm_docs ../user/Test-Tiers.md %}
+{% gfm_docs ../user/Troubleshooting.md %}
+
+{% copy_assets ../user/assets %}

docs/site/01-python-developers.md

@@ -33,7 +33,7 @@ You can extend it with Python code or leverage packages from the Python ecosyste
             Do you want to test your Python application or package on GraalPy?
           </h5>
           <h5 class="download-text">
-            To test Python code on GraalPy, a standalone distribution is available for different platforms and in two different kinds: <a href="{{ '/docs/#graalpy-distributions' | relative_url }}">Native</a> (for compact download and footprint) and <a href="{{ '/docs/#graalpy-distributions' | relative_url }}">JVM</a> (for full Java interoperability). We recommend the distributions based on Oracle GraalVM for best performance and advanced features (released under the <a target="_blank" href="https://www.oracle.com/downloads/licenses/graal-free-license.html">GFTC license</a>). Distributions based on GraalVM Community Edition (released under the OSI-approved <a target="_blank" href="https://github.com/oracle/graalpython/blob/master/LICENSE.txt">UPL license</a>) are available on <a href="https://github.com/oracle/graalpython/releases" target="_blank">GitHub</a>. Standalone distributions are also available via <a target="_blank" href="{{ 'docs#installing-graalpy' | relative_url }}">pyenv</a>, <a target="_blank" href="{{ 'docs#installing-graalpy' | relative_url }}">pyenv-win</a>, and <a target="_blank" href="https://github.com/actions/setup-python?tab=readme-ov-file#basic-usage">setup-python</a>:
+            To test Python code on GraalPy, a standalone distribution is available for different platforms and in two different kinds: <a href="{{ '/docs/python-developers/' | relative_url }}">Native</a> (for compact download and footprint) and <a href="{{ '/docs/python-developers/' | relative_url }}">JVM</a> (for full Java interoperability). We recommend the distributions based on Oracle GraalVM for best performance and advanced features (released under the <a target="_blank" href="https://www.oracle.com/downloads/licenses/graal-free-license.html">GFTC license</a>). Distributions based on GraalVM Community Edition (released under the OSI-approved <a target="_blank" href="https://github.com/oracle/graalpython/blob/master/LICENSE.txt">UPL license</a>) are available on <a href="https://github.com/oracle/graalpython/releases" target="_blank">GitHub</a>. Standalone distributions are also available via <a target="_blank" href="{{ 'docs/python-developers/' | relative_url }}">pyenv</a>, <a target="_blank" href="{{ 'docs/python-developers/' | relative_url }}">pyenv-win</a>, and <a target="_blank" href="https://github.com/actions/setup-python?tab=readme-ov-file#basic-usage">setup-python</a>:
           </h5>
         </div>
         <div class="languages__example-card">

docs/site/02-downloads.md

@@ -0,0 +1,39 @@
+---
+layout: docs
+title: Java Developers
+permalink: docs/java-developers/
+docs_index: java-developers
+nav_order: 2
+---
+
+# GraalPy for Java Developers
+
+**For Java developers who need to use Python libraries from their Java applications or migrate from legacy Jython code.**
+
+You do not need to install GraalPy separately - you can use GraalPy directly in Java with Maven or Gradle.
+This lets you call Python libraries like NumPy, pandas, or any PyPI package from your Java application.
+GraalPy also provides a migration path from Jython 2.x to Python 3.x with better performance and maintained Java integration capabilities.
+
+{% gfm_docs ../user/Version-Compatibility.md %}
+
+{% gfm_docs ../user/Platform-Support.md %}
+
+These guides cover everything you need to know:
+
+{% gfm_docs ../user/Embedding-Getting-Started.md %}
+{% gfm_docs ../user/Embedding-Build-Tools.md %}
+{% gfm_docs ../user/Embedding-Permissions.md %}
+{% gfm_docs ../user/Interoperability.md %}
+{% gfm_docs ../user/Native-Images-with-Python.md %}
+{% gfm_docs ../user/Python-on-JVM.md %}
+
+<h3 id="python-context-options">
+<a href="#python-context-options" class="anchor-link">Python Context Options</a>
+</h3>
+Below are the options you can set on contexts for GraalPy.
+{% python_options ../../graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonOptions.java %}
+
+{% gfm_docs ../user/Test-Tiers.md %}
+{% gfm_docs ../user/Troubleshooting.md %}
+
+{% copy_assets ../user/assets %}

docs/site/02-java-developers.md

@@ -2,6 +2,7 @@
 layout: base
 title: Compatibility
 permalink: compatibility/
+nav_order: 3
 ---
 
 <style>

docs/site/03-compatibility.md

@@ -0,0 +1,15 @@
+---
+layout: docs
+permalink: docs/
+redirect_to: docs/python-developers/
+---
+
+<script>
+window.location.replace('/python/docs/python-developers/');
+</script>
+
+<noscript>
+<meta http-equiv="refresh" content="0; url=/python/docs/python-developers/" />
+</noscript>
+
+<p>Redirecting to <a href="/python/docs/python-developers/">Python Developers documentation</a>...</p>