split user and contributor docs

Author: timfel

README.md

@@ -72,9 +72,16 @@ manually for now.
 
 ### Polyglot Usage
 
-We have a [document](doc/POLYGLOT.md) describing how we implement the
+We have a [document](docs/user/POLYGLOT.md) describing how we implement the
 cross-language interop. This will hopefully give you an idea how to use it.
 
+### Jython Support
+
+We are working on a mode that is "mostly compatible" with some of Jython's
+features, minus of course that Jython implements Python 2.7 and we implement
+Python 3.7+. We describe the current status of the compatibility mode
+[here](docs/user/JYTHON.md).
+
 ### Contributing
 
 I you're thinking about contributing something to this repository, you will need
@@ -83,7 +90,7 @@ Agreement](http://www.graalvm.org/community/contributors/) for us to able to
 merge your work. Please also take note of our [code of
 conduct](http://www.graalvm.org/community/conduct/) for contributors.
 
-To get you started, we have [written a bit](doc/CONTRIBUTING.md) about the
+To get you started, we have [written a bit](docs/contributor/CONTRIBUTING.md) about the
 structure of this interpreter that should show how to fix things or add
 features.
 

doc/CONTRIBUTING.md renamed to docs/contributor/CONTRIBUTING.md

@@ -8,7 +8,7 @@ merge your work.
 
 Please also take some time to review our [code of conduct](http://www.graalvm.org/community/conduct/) for contributors.
 
-##### Getting started
+### Getting started
 
 The first thing you want to do is to set up
 [mx](https://github.com/graalvm/mx.git). This is the build tool we use to
@@ -38,7 +38,7 @@ projects in these IDEs. If you use another editor with support for the [Eclipse
 language server](https://github.com/eclipse/eclipse.jdt.ls) we also had reports
 of useable development setups with that, but it's not something we support.
 
-##### Development layout
+### Development layout
 
 Besides the source code of the Python interpreter, we have some useful `mx`
 functions defined under the `mx.graalpython` directory. As you make changes, you
@@ -76,7 +76,7 @@ The C implementation and headers for our C API are in
 Python's source names. This folder also includes a `modules` folder for built-in
 modules that we have adapted from C Python.
 
-##### Debug options
+### Debug options
 
 The GraalVM implementation of Python provides proper debug options. It is possible to either debug the Python code, using Chrome debugger,   
 or the java code, using your preferred IDE.

docs/contributor/DEV_TASKS.md

@@ -0,0 +1,27 @@
+# Dev Tasks For Graal Python Developers
+
+### Updating dependencies
+
+We can use the following command to update our CI jsonnet as well as all
+dependencies (truffle, sulong, ...) in one go:
+
+    mx python-update-import
+
+This should be run on a clean branch that you'll use for the PR. It will search
+adjacent directories for other `graalpython*` repositories (such as external
+extensions you might have locally) and check if it needs to update something in
+those as well. It will also make sure that the CI jsonnet is in sync with the
+Graal updates etc. In the end it will tell you which repositories were updated
+and pushed. Make sure you open PRs and merge them at the same time for all of
+these.
+
+### Updating lib-python
+
+The following command, run on a clean branch, should guide you through updating
+our imported sources from CPython and PyPy:
+
+    mx python-src-import
+
+It prints a fairly long help. Note that you'll need to make sure you also pushed
+your `python-import` branch after doing the update, so that any conflicts you
+resolved don't have to be resolved again by the next person.

doc/IMPLEMENTATION_DETAILS.md renamed to docs/contributor/IMPLEMENTATION_DETAILS.md

@@ -1,6 +1,6 @@
 # Implementation Details
 
-## Python Global Thread State
+### Python Global Thread State
 
 In CPython, each stack frame is allocated on the heap, and there's a global
 thread state holding on to the chain of currently handled exceptions (e.g. if
@@ -80,7 +80,7 @@ exception. Unlike CPython we do not use a stack of currently handled exceptions,
 instead we utilize the call stack of Java by always passing the current exception
 and holding on to the last (if any) in a local variable.
 
-## Abstract Operations on Python Objects
+### Abstract Operations on Python Objects
 
 Many generic operations on Python objects in CPython are defined in the header
 files `abstract.c` and `abstract.h`. These operations are widely used and their

doc/JYTHON.md renamed to docs/user/JYTHON.md

@@ -0,0 +1,53 @@
+# Installing Supported Packages
+
+### Create a virtual environment
+
+The best way of using the GraalVM implementation of Python is out of a virtual
+environment. This generates wrapper scripts and makes the implementation usable
+from shell as standard Python interpreter. To do so execute the following from a
+GraalVM installation:
+
+```
+graalpython -m venv <venv-dir>
+```
+
+To activate the environment in your shell session call:
+
+```
+source <venv-dir>/bin/activate
+```
+
+### Using ginstall
+
+At the moment not enough of the standard library is implemented to run the
+standard package installers for many packages. As a convenience, we provide a
+simple module to install packages that we know to be working (including
+potential patches required for those packages). Try the following to find out
+more:
+
+```
+graalpython -m ginstall --help
+```
+
+As a slightly more exciting example, try:
+
+```
+graalpython -m ginstall install numpy
+```
+
+If all goes well (also consider native dependencies of NumPy), you should be
+able to `import numpy` afterwards.
+
+Support for more extension modules is high priority for us. We are actively
+building out our support for the Python C API to make extensions such as NumPy,
+SciPy, Scikit-learn, Pandas, Tensorflow and the like work. This work means that
+some other extensions might also already work, but we're not actively testing
+other extensions right now and cannot promise anything. Note that to try
+extensions on this implementation, you have to download, build, and install them
+manually for now.
+
+### Using PIP
+
+The pip package installer is available and working in a `venv`, but we currently
+have no support for SSL. That means you can install packages from PyPI if you
+use an HTTP mirror and you can install local packages.

docs/user/PACKAGES.md

@@ -0,0 +1,6 @@
+# The Python Implementation for GraalVM
+
+A primary goal of this Python implementation is to support SciPy and its
+constituent libraries as well as work with other data science and machine
+learning libraries from the rich Python ecosystem. At this point, the Python
+implementation is made available for experimentation and curious end-users.

doc/POLYGLOT.md renamed to docs/user/POLYGLOT.md

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -112,9 +112,9 @@ public void initialize(PythonCore core) {
         String coreHome = context.getCoreHome();
         try {
             TruffleFile coreDir = env.getInternalTruffleFile(coreHome);
-            TruffleFile docDir = coreDir.resolveSibling("doc");
-            if (docDir.exists() || docDir.getParent() != null && (docDir = coreDir.getParent().resolveSibling("doc")).exists()) {
-                builtinConstants.put(SpecialAttributeNames.__DOC__, new String(docDir.resolve("INTEROP.md").readAllBytes()));
+            TruffleFile docDir = coreDir.resolveSibling("docs");
+            if (docDir.exists() || docDir.getParent() != null && (docDir = coreDir.getParent().resolveSibling("docs")).exists()) {
+                builtinConstants.put(SpecialAttributeNames.__DOC__, new String(docDir.resolve("user").resolve("POLYGLOT.md").readAllBytes()));
             }
         } catch (SecurityException | IOException e) {
         }

docs/user/README.md

@@ -380,7 +380,7 @@
             "description": "Graal.Python documentation files for the GraalVM",
             "layout": {
                 "README_GRAALPYTHON.md": "file:README.md",
-                "./": "file:doc",
+                "./": "file:docs",
             },
             "maven": False,
         },