Merge pull request #12 from adamburkegh/bug2758_jarray

Jython features page and Jython registry page. Deeplink to book for

Author: jamesmudd

_data/book.yml

@@ -0,0 +1,16 @@
+---
+baseurl: https://jython.readthedocs.io/en/latest/
+
+intro: 
+    url: chapter1/
+
+datatypes: 
+    url: chapter2/
+
+integration:
+    url: chapter10/
+
+database: 
+    url: chapter12/
+
+

_data/pydoc.yml

@@ -0,0 +1,4 @@
+baseurl: https://docs.python.org/2.7/
+
+liburl: https://docs.python.org/2.7/library/
+

index.md

@@ -28,7 +28,15 @@ print('Running on Java version: ' + System.getProperty('java.version'))
 print('Unix time from Java: ' + str(System.currentTimeMillis()))
 ```
 
- Ready to get started? Head over to [Downloads](download)
+## Getting Started
+
+ Ready to get started? Head over to [Downloads](download).
+
+ Or you could read a quick overview of [features specific to Jython](jyspecific).
+
+ A more detailed introduction and reference can be found in the [Jython Book]({{site.data.book.baseurl}}).
+
+
 
 ## Who uses Jython?
 Jython is embedded in lots of projects. See some from [MVNRepository](https://mvnrepository.com/artifact/org.python/jython-standalone/usages)

jyspecific.md

@@ -0,0 +1,39 @@
+---
+title: Jython-Specific Features
+---
+
+{% assign book = site.data.book.baseurl %}
+{% assign datatypes   = book | append: site.data.book.datatypes['url'] %} 
+{% assign integration = book | append: site.data.book.integration['url'] %} 
+{% assign database    = book | append: site.data.book.database['url'] %} 
+
+# Jython-Specific Features
+
+Jython has a number of features which allow easier integration with Java and make use of the rich environment provided by joining the two languages.
+
+
+## The Jython Registry
+
+Jython works with a [local Jython registry file](registry) to provide a platform independent equivalent to the Windows registry. It combines this with environment variable and command line information at startup.
+
+
+## Embedding
+
+Java classes can be [embedded in Python scripts]({{integration}}#using-java-within-jython-applications), and Python scripts invoked and inspected [from Java code]({{integration}}#using-jython-within-java-applications).  
+
+
+## Collection and Array support 
+
+Jython provides ways to smoothly integrate [Java collections and arrays]({{datatypes}}#jython-specific-collections) with Python data structures. 
+
+
+## Compiling to Java class files
+
+The [`compileall` module]({{site.data.pydoc.liburl}}compileall.html) in Jython produces Java byte code in Java class files from Python code. It otherwise corresponds to the CPython module of the same name. (Earlier versions used a tool called jythonc which was removed fully in Jython 2.5).
+
+
+## Database interaction
+
+The [zxjdbc module]({{database}}) provides a Pythonesque interface on top of the Java Database Connectivity API (JDBC).
+
+

registry.md

@@ -0,0 +1,57 @@
+---
+title: Jython Registry
+---
+
+# Jython Registry
+
+Because there is no good platform independent equivalent of the Windows Registry (or Unix envrionment variables) Java has it's own environment variable namespace. Jython aquires it's namespace from the following sources (later sources override defaults found in earlier places).
+
+ - The Java system properties: typically passed in on the command line as options to the java interpreter.
+ - The Jython "registry" file, which contains prop=value pairs. See below for the algorithm Jython uses to find the registry file.
+ - The user's personal registry file, which contains similarly formated prop/value pairs. The user's registry file is at `"user.home"+"/.jython"`
+ - Jython properties: Specified on the command line as options to the jython class. See the -D option to the interpreter.
+
+## Registry Properties
+
+The following properties are recognized by Jython. More detailed documentation may be found in comments in the `registry` file provided with the Jython distribution. 
+
+**python.path**
+Equivalent to CPython's `PYTHONPATH` environment variable
+
+**python.cachedir**
+The directory to use for caches - currently just package information. This directory must be writable by the user. If the directory is an absolute path, it is used as given, otherwise it is interpreted as relative to sys.prefix.
+
+**python.verbose**
+Sets the verbosity level for varying degrees of informative messages. Valid values in order of increasing verbosity are "error", "warning", "message", "comment", "debug"
+
+**python.security.respectJavaAccessibility**
+Normally, Jython can only provide access to public members of classes. If this property is set to false, and you are using a Java version before Java 9, then Jython can access non-public fields, methods, and constructors. This may be deprecated in the future due to Java changes to accessibility from version 9.
+
+**python.console**
+The name of a console class. An alternative console class that supports GNU readline can be installed with this property. Jython already include such a console class and it can be enabled by setting this property to `org.python.util.ReadlineConsole`.
+
+**python.console.readlinelib**
+Allow a choice of backing implementation for GNU readline support. Can be either GnuReadline or Editline. This property is only used when python.console is set to org.python.util.ReadlineConsole.
+
+**python.startup**
+File to be run at the start of each interactive session, but not when dropping in with the -i flag in after a script has run.
+
+**python.modules.builtin**
+Add, remove, or override built in modules.
+
+**python.cpython2**
+Command used to invoke CPython, when needed, as in the case of modules and methods longer than Java supports natively.
+
+
+
+
+## Finding the Registry File
+
+The following steps are used to find the Jython registry file, and also to set the Python values for `sys.prefix`. First a root directory is calculated:
+
+ - If there is a property called `python.home`, this is used as the root directory.
+ - Otherwise, the property `install.root` is used if it exists.
+ - If neither of those properties exist, then Jython searches for the file "jython.jar" on the Java classpath, as defined in the system property `java.class.path`. The actual file system isn't searched, only the paths defined on the classpath (one of them must literally include "jython.jar").
+
+Once the root directory is found, `sys.prefix` and `sys.exec_prefix` are set to this, and `sys.path` has rootdir/Lib appended to it. The registry file used is then rootdir/registry.
+