[GR-32720] Set up documentation versioning and use rel paths.

PullRequest: graalpython/1980

Author: olyagpl

docs/user/FAQ.md

@@ -46,7 +46,7 @@ For native extensions running as LLVM bitcode, CPython is currently slower -- yo
 ### I heard languages with JIT compilers have slow startup. Is that true for GraalVM's Python runtime?
 
 It depends.
-When you use [Native Image](https://www.graalvm.org/reference-manual/native-image/) with Python, or the `graalpython` launcher of GraalVM, startup is competitive with CPython.
+When you use [Native Image](https://github.com/oracle/graal/blob/master/docs/reference-manual/native-image/README.md) with Python, or the `graalpython` launcher of GraalVM, startup is competitive with CPython.
 In any case, both with Native Image or when running on the JVM, you first need to warm up to reach peak performance. This is a complicated story in itself, but, in general, it can take a while (a minute or two) after you have reached and are running your core workload.
 
 ### Can I share warmed-up code between multiple Python contexts?

docs/user/Interoperability.md

@@ -188,7 +188,7 @@ print(java.instanceof(my_list, ArrayList))
 # prints True
 ```
 
-See [Polyglot Programming](https://www.graalvm.org/reference-manual/polyglot-programming/) and [Embed Languages](https://www.graalvm.org/reference-manual/embed-languages/) for more information about interoperability with other programming languages.
+See [Polyglot Programming](https://github.com/oracle/graal/blob/master/docs/reference-manual/polyglot-programming.md) and [Embed Languages](https://github.com/oracle/graal/blob/master/docs/reference-manual/embedding/embed-languages.md) for more information about interoperability with other programming languages.
 
 ## The Behaviour of Types
 
@@ -197,18 +197,12 @@ ways and have restrictions on how they can interact with Python.
 
 ### Interop Types to Python
 
-Most importantly and upfront - all foreign objects passing into Python have the
-Python type `foreign`. There is no emulation of i.e., objects that are interop
-booleans to have the Python type `bool`. This is because interop types can
-overlap in ways that the Python builtin types cannot, and it would not be clear
-what should take precendence. Instead, the `foreign` type defines all of the
-Python special methods for type conversion that are used throughout the
-interpreter (methods like `__add__`, `__int__`, `__str__`, `__getitem__` etc)
-and these try to do the right thing based on the interop type (or raise an
-exception.)
-
-Types not listed in the below table have no special interpretation in Python
-right now.
+Most importantly and upfront - all foreign objects passing into Python have the Python type `foreign`.
+There is no emulation of i.e., objects that are interop booleans to have the Python type `bool`.
+This is because interop types can overlap in ways that the Python builtin types cannot, and it would not be clear what should take precendence.
+Instead, the `foreign` type defines all of the Python special methods for type conversion that are used throughout the interpreter (methods like `__add__`, `__int__`, `__str__`, `__getitem__`, etc.) and these try to do the right thing based on the interop type (or raise an exception.)
+
+Types not listed in the below table have no special interpretation in Python right now.
 
 | Interop type | Python interpretation                                                                                                                                                                                                                                                                                                |
 |:-------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

docs/user/Jython.md

@@ -245,4 +245,4 @@ There are no APIs particular to Python that are exposed, and everything is done
 
 It is important to note that as long as your application is executed on GraalVM with the Python language installed,
 you can embed Python in your programs.
-For more details, refer to the [Embed Languages](https://www.graalvm.org/reference-manual/embed-languages/) guide.
+For more details, refer to the [Embed Languages](https://github.com/oracle/graal/blob/master/docs/reference-manual/embedding/embed-languages.md) guide.

docs/user/OsInterface.md

@@ -1,38 +1,31 @@
+---
+layout: docs-experimental
+toc_group: python
+link_title: Operating System Interfaces
+permalink: /reference-manual/python/OSInterface/
+---
+
 # Operating System Interfaces
 
-Truffle based GraalVM languages usually implement the system related
-functions using the [Truffle abstraction layer](https://www.graalvm.org/graalvm-as-a-platform/language-implementation-framework/), which is OS independent
-and provides extension points for the users when embedding GraalVM Python
-or other Truffle based languages into Java applications. See, for example,
-[Truffle FileSystem service-provider](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/io/FileSystem.html).
+Truffle-based GraalVM languages usually implement the system related functions using the [Truffle abstraction layer](https://github.com/oracle/graal/blob/master/truffle/docs/README.md), which is OS independent and provides extension points for the users when embedding GraalVM Python or other Truffle based languages into Java applications.
+See, for example, [Truffle FileSystem service-provider](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/io/FileSystem.html).
 
-The Python standard library also provides OS abstraction, but exposes lower level interfaces,
-for instance, the OS module directly exposes some POSIX functions. On non-POSIX platforms,
-this interface is emulated to a degree.
+The Python standard library also provides OS abstraction, but exposes lower level interfaces, for instance, the OS module directly exposes some POSIX functions.
+On non-POSIX platforms, this interface is emulated to a degree.
 
-GraalVM Python runtime provides two alternative implementations of the system related
-functionality offered by the builtin Python modules such as `os`.
-Which implementation is used can be controlled by the option `PosixModuleBackend`:
-valid values are `native` and `java`.
+GraalVM Python runtime provides two alternative implementations of the system related functionality offered by the builtin Python modules such as `os`.
+Which implementation is used can be controlled by the option `PosixModuleBackend`: valid values are `native` and `java`.
 
 ## Native backend
 
-The `native` backend calls directly the POSIX API in mostly the same way
-as CPython, the reference Python implementation, does.
+The `native` backend calls directly the POSIX API in mostly the same way as CPython, the reference Python implementation, does.
 
-This approach is the most compatible with CPython and provides bare access
-to the underlying OS interface without any emulation layer in between.
+This approach is the most compatible with CPython and provides bare access to the underlying OS interface without any emulation layer in between.
 
-By default, this implementation bypasses the Truffle abstraction layer,
-therefore it is not sandboxed and does not support custom implementations
-of [Truffle FileSystem service-provider](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/io/FileSystem.html)
-and other Polyglot API providers related to system interfaces.
+By default, this implementation bypasses the Truffle abstraction layer, therefore it is not sandboxed and does not support custom implementations of [Truffle FileSystem service-provider](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/io/FileSystem.html) and other Polyglot API providers related to system interfaces.
 
-The native backend is chosen by default when GraalVM Python
-is started via the `graalpython` or any other Python related
-launcher inside GraalVM. The exception are Python related launchers
-with `-managed` suffix available only in GraalVM Enterprise
-(e.g., `graalpython-managed`), which by default use the `java` POSIX backend.
+The native backend is chosen by default when GraalVM Python is started via the `graalpython` or any other Python related launcher inside GraalVM.
+The exception are Python related launchers with `-managed` suffix available only in GraalVM Enterprise (e.g., `graalpython-managed`), which by default use the `java` POSIX backend.
 
 ### Limitations of the native backend
 
@@ -43,21 +36,15 @@ Known limitations:
 
 ## Java backend
 
-The `java` backend uses the [Truffle abstraction layer](https://www.graalvm.org/graalvm-as-a-platform/language-implementation-framework/)
-and therefore supports custom Polyglot API providers related to system interfaces and sandboxing.
-Since this abstraction is POSIX agnostic, it does not expose
-all the necessary functionality. Some functionality is emulated, and some
-functionality is not supported at all.
+The `java` backend uses the [Truffle abstraction layer](https://github.com/oracle/graal/blob/master/truffle/docs/README.md) and therefore supports custom Polyglot API providers related to system interfaces and sandboxing.
+Since this abstraction is POSIX agnostic, it does not expose all the necessary functionality. Some functionality is emulated, and some functionality is not supported at all.
 
-The java backend is the default when GraalVM Python is run via
-the `Context` API, i.e., [embedded in Java applications](https://www.graalvm.org/reference-manual/embed-languages), or when it is launched using Python related launchers
-with `-managed` suffix available only in GraalVM Enterprise.
+The java backend is the default when GraalVM Python is run via the `Context` API, i.e., [embedded in Java applications](https://github.com/oracle/graal/blob/master/docs/reference-manual/embedding/embed-languages.md), or when it is launched using Python related launchers with `-managed` suffix available only in GraalVM Enterprise.
 
 ### Limitations of the emulated backend
 
-GraalVM Python can log info about known incompatibility of functions executed at runtime,
-which includes the OS interface related functions. To turn on this logging use
-`--log.python.compatibility=FINE` or other desired logging level.
+GraalVM Python can log info about known incompatibility of functions executed at runtime, which includes the OS interface related functions.
+To turn on this logging, use `--log.python.compatibility=FINE` or other desired logging level.
 
 Known limitations of the emulated layer are:
 
@@ -76,12 +63,8 @@ Known limitations of the emulated layer are:
 
 ## Relation to Python native extensions
 
-Apart from operating system interfaces exposed as builtin Python level modules,
-Python native extensions executed via the GraalVM LLVM runtime may also access
-OS interfaces at the C level. How such accesses are handled depends on the
-GraalVM LLVM runtime configuration.
+Apart from operating system interfaces exposed as builtin Python level modules, Python native extensions executed via the GraalVM LLVM runtime may also access OS interfaces at the C level.
+How such accesses are handled depends on the GraalVM LLVM runtime configuration.
 
-At this point, the only combination where OS handles, such as file descriptors,
-can be shared between Python and the C code of Python extensions is with
-`native` PosixModuleBackend and `native` mode of GraalVM LLVM runtime.
-This combination is the default for the `graalpython` launcher.
+At this point, the only combination where OS handles, such as file descriptors, can be shared between Python and the C code of Python extensions is with `native` PosixModuleBackend and `native` mode of GraalVM LLVM runtime.
+This combination is the default for the `graalpython` launcher.

docs/user/ParserDetails.md

@@ -14,7 +14,7 @@ This guide elaborates on how Python files are parsed on the GraalVM Python runti
 
 Creating the abstract syntax tree (AST) for a Python source has two phases.
 The first one creates a simple syntax tree (SST) and a scope tree.
-The second phase transforms the SST to the [Language Implementation framework](https://www.graalvm.org/graalvm-as-a-platform/language-implementation-framework/) tree.
+The second phase transforms the SST to the [Truffle Language Implementation framework](https://github.com/oracle/graal/blob/master/truffle/docs/README.md) tree.
 
 For the transformation, the scope tree it needed.
 The scope tree contains scope locations for variable and function definitions, and information about scopes.

docs/user/README.md

@@ -15,13 +15,12 @@ See [FAQ](FAQ.md) for commonly asked questions about this implementation.
 
 ## Installing Python
 
-The Python runtime is not provided by default, and can be added to GraalVM with the [GraalVM Updater](https://www.graalvm.org/reference-manual/graalvm-updater), `gu`, tool:
+The Python runtime is not provided by default, and can be added to GraalVM with the [GraalVM Updater](https://github.com/oracle/graal/blob/master/docs/reference-manual/graalvm-updater.md), `gu`, tool:
 ```shell
 gu install python
 ```
 
-The above command will install Python from the GitHub catalog for GraalVM Community Edition users.
-For GraalVM Enterprise users, the [manual installation](https://www.graalvm.org/reference-manual/graalvm-updater/#manual-installation) is required.
+The above command will install Python from the catalog.
 
 ## Running Python
 
@@ -70,7 +69,7 @@ For more information, continue reading to the [Installing Supported Packages](Pa
 
 ## Native Image and JVM Runtime
 
-By default, GraalVM runs Python from a binary, compiled ahead-of-time with [Native Image](https://www.graalvm.org/reference-manual/native-image/), yielding faster startup time and lower footprint.
+By default, GraalVM runs Python from a binary, compiled ahead-of-time with [Native Image](https://github.com/oracle/graal/blob/master/docs/reference-manual/native-image/README.md), yielding faster startup time and lower footprint.
 Although the ahead-of-time compiled binary includes the Python and LLVM interpreters, in order to interoperate with
 other languages you have to supply the `--jvm` argument.
 This instructs the launcher to run on the JVM instead of in Native Image mode.

docs/user/Tooling.md

@@ -21,7 +21,7 @@ To start debugging, open the following URL in Chrome:
     chrome-devtools://devtools/bundled/js_app.html?ws=127.0.1.1:9229/76fcb6dd-35267eb09c3
 ```
 
-The standard Python built-in `breakpoint()` will work using the [GraalVM's Chrome Inspector](https://www.graalvm.org/tools/chrome-debugger/) implementation.
+The standard Python built-in `breakpoint()` will work using the [GraalVM's Chrome Inspector](https://github.com/oracle/graal/blob/master/docs/tools/chrome-debugger.md) implementation.
 You can inspect variables, set watch expressions, interactively evaluate code snippets, etc.
 However, this only works if you pass `--inspect` or some other inspect option. Otherwise, `pdb` is triggered as on CPython (and does not currently work).