Doc updates

Author: dbrattli

docs-src/_config.yml

@@ -2,7 +2,7 @@
 # Learn more at https://jupyterbook.org/customize/config.html
 
 title: Fable Python
-author: By the Fable community
+author: the Fable community
 logo: logo.png
 
 # Force re-execution of notebooks on each build.

docs-src/_toc.yml

@@ -4,7 +4,6 @@
 format: jb-book
 root: index
 chapters:
-- file: index.md
 - file: intro.md
 - file: introduction/dotnet-users-read-this
 - file: introduction/py-users-read-this

docs-src/communicate/fable-from-py.md

@@ -48,15 +48,15 @@ module Bar =
 
 In some cases, it's possible to change the default behavior towards name mangling:
 
-- If you want to have all members attached to a class (as in standard JS classes) and not-mangled use the `AttachMembers` attribute. But be aware **overloads won't work** in this case.
-- If you are not planning to use an interface to interact with JS and want to have overloaded members, you can decorate the interface declaration with the `Mangle` attribute. Note: Interfaces coming from .NET BCL (like System.Collections.IEnumerator) are mangled by default.
+- If you want to have all members attached to a class (as in standard Python classes) and not-mangled use the `AttachMembers` attribute. But be aware **overloads won't work** in this case.
+- If you are not planning to use an interface to interact with Python and want to have overloaded members, you can decorate the interface declaration with the `Mangle` attribute. Note: Interfaces coming from .NET BCL (like System.Collections.IEnumerator) are mangled by default.
 
 ## Common types and objects
 
-Some F#/.NET types have [counterparts in JS](../dotnet/compatibility.md). Fable takes advantage of this to compile to native types that are more performant and reduce bundle size. You can also use this to improve interop when exchanging data between F# and JS. The most important common types are:
+Some F#/.NET types have [counterparts in JS](../dotnet/compatibility.md). Fable takes advantage of this to compile to native types that are more performant and reduce bundle size. You can also use this to improve interop when exchanging data between F# and Python. The most important common types are:
 
-- **Strings and booleans** behave the same in F# and JS.
-- **Chars** are compiled as JS strings of length 1. This is mainly because string indexing in JS gives you another string. But you can use a char as a number with an explicit conversion like `int16 '家'`.
+- **Strings and booleans** behave the same in F# and Python.
+- **Chars** are compiled as Python strings of length 1. This is mainly because string indexing in JS gives you another string. But you can use a char as a number with an explicit conversion like `int16 '家'`.
 - **Numeric types** compile to JS numbers, except for `long`, `decimal` and `bigint`.
 - **Arrays** (and `ResizeArray`) compile to JS arrays. _Numeric arrays_ compile to [Typed Arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) in most situations, though this shouldn't make a difference for most common operations like indexing, iterating or mapping. You can disable this behavior with [the `typedArrays` option](https://www.npmjs.com/package/fable-loader#options).
 - Any **IEnumerable** (or `seq`) can be traversed in JS as if it were an [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators#Iterables).

docs-src/communicate/py-from-fable.md

@@ -1,20 +1,28 @@
 # Call Python from Fable
 
-Interoperability is a matter of trust between your statically typed F# code and your untyped dynamic JS code. In order to mitigate risks, Fable gives you several possibilities, amongst them type safety through interface contracts. Sometimes it may sound more convenient to just call JS code in a more dynamic fashion, although be aware by doing this potential bugs will not be discovered until runtime.
+Interoperability is a matter of trust between your statically typed F# code and your untyped dynamic JS code. In order
+to mitigate risks, Fable gives you several possibilities, amongst them type safety through interface contracts.
+Sometimes it may sound more convenient to just call JS code in a more dynamic fashion, although be aware by doing this
+potential bugs will not be discovered until runtime.
 
 We'll describe both the safe way and the dynamic way and then it will be up to you to decide. Let's start!
 
 ## Adding the JS library to the project
 
-The very first thing to do is add the library to our project. Since we always have a `package.json` file, we'll just add the wanted library to our project using either `npm install my-awesome-js-library`. The library will then be available in the `node_modules` folder.
+The very first thing to do is add the library to our project. Since we always have a `package.json` file, we'll just add
+the wanted library to our project using either `npm install my-awesome-js-library`. The library will then be available
+in the `node_modules` folder.
 
 > If your library is in a file, just skip this step.
 
 ## Type safety with Imports and Interfaces
 
-To use code from JS libraries first you need to import it into F#. For this Fable uses [ES2015 imports](https://developer.mozilla.org/en/docs/web/JavaScript/reference/statements/import), which can be later transformed to other JS module systems like `commonjs` or `amd` by [Babel](https://babeljs.io/docs/en/plugins#modules).
+To use code from JS libraries first you need to import it into F#. For this Fable uses [ES2015
+imports](https://developer.mozilla.org/en/docs/web/JavaScript/reference/statements/import), which can be later
+transformed to other JS module systems like `commonjs` or `amd` by [Babel](https://babeljs.io/docs/en/plugins#modules).
 
-There are two ways to declare ES2015 imports in Fable: by using either the **Import attribute** or the **import expressions**. The `ImportAttribute` can decorate members, types or modules and works as follows:
+There are two ways to declare ES2015 imports in Fable: by using either the **Import attribute** or the **import
+expressions**. The `ImportAttribute` can decorate members, types or modules and works as follows:
 
 ```fsharp
 // Namespace imports
@@ -34,28 +42,28 @@ You can also use the following alias attributes:
 
 ```fsharp
 open Fable.Core
-open Fable.Core.JsInterop
+open Fable.Core.PyInterop
 
 // Same as Import("*", "my-module")
 [<ImportAll("my-module")>]
-let myModule: obj = jsNative
+let myModule: obj = nativeOnly
 
 // Same as Import("default", "my-module")
 [<ImportDefault("my-module")>]
-let myModuleDefaultExport: obj = jsNative
+let myModuleDefaultExport: obj = nativeOnly
 
 // The member name is taken from decorated value, here `myFunction`
 [<ImportMember("my-module")>]
-let myFunction(x: int): int = jsNative
+let myFunction(x: int): int = nativeOnly
 ```
 
 If the value is globally accessible in JS, you can use the `Global` attribute with an optional name parameter instead.
 
 ```fsharp
-let [<Global>] console: JS.Console = jsNative
+let [<Global>] console: JS.Console = nativeOnly
 
 // You can pass a string argument if you want to use a different name in your F# code
-let [<Global("console")>] logger: JS.Console = jsNative
+let [<Global("console")>] logger: JS.Console = nativeOnly
 ```
 
 ### Importing relative paths when using an output directory
@@ -64,25 +72,25 @@ If you are putting the generated JS files in an output directory using Fable's `
 
 ```fsharp
 [<ImportDefault("${outDir}/../styles/styles.module.css")>]
-let styles: CssModule = jsNative
+let styles: CssModule = nativeOnly
 ```
 
 Let's say we're compiling with the `-o build` option and the file ends up in the `build/Components` directory. The generated code will look like:
 
 ```js
-import styles from "../../styles/styles.module.css"
+import styles from "../../styles/styles.module.css";
 ```
 
 ### OOP Class definition and inheritance
 
-Assuming we need to import a JS class, we can represent it in F# using a standard class declaration with an `Import` attribute. In this case we use `jsNative` as a dummy implementation for its members as the actual implementation will come from JS. When using `jsNative` don't forget to add the return type to the member!
+Assuming we need to import a JS class, we can represent it in F# using a standard class declaration with an `Import` attribute. In this case we use `nativeOnly` as a dummy implementation for its members as the actual implementation will come from JS. When using `nativeOnly` don't forget to add the return type to the member!
 
 ```fsharp
 [<Import("DataManager", from="library/data")>]
 type DataManager<'Model> (conf: Config) =
-    member _.delete(data: 'Model): Promise<'Model> = jsNative
-    member _.insert(data: 'Model): Promise<'Model> = jsNative
-    member _.update(data: 'Model): Promise<'Model> = jsNative
+    member _.delete(data: 'Model): Promise<'Model> = nativeOnly
+    member _.insert(data: 'Model): Promise<'Model> = nativeOnly
+    member _.update(data: 'Model): Promise<'Model> = nativeOnly
 ```
 
 From this point it is possible to use it or even to inherit from it as it is usually done on regular F#, [see the official F# documentation](https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/inheritance). If you want to inherit and override a member, F# requires you to declare the member as `abstract` in the base class, with a default implementation if you want to make it also directly usable from the base class. For example:
@@ -92,7 +100,7 @@ From this point it is possible to use it or even to inherit from it as it is usu
 [<Import("DataManager", from="library.data")>]
 type DataManager<'T> (conf: Config) =
     abstract update: data: 'T -> Promise<'T>
-    default _.update(data: 'T): Promise<'T> = jsNative
+    default _.update(data: 'T): Promise<'T> = nativeOnly
 
 // This class lives in our code
 type MyDataManager<'T>(config) =
@@ -146,15 +154,15 @@ Now let's use this:
 
 ```fsharp
   [<ImportAll("path/to/alert.js")>]
-  let mylib: IAlert = jsNative
+  let mylib: IAlert = nativeOnly
 ```
 
 Here we use the `ImportAll` attribute, which is the same as `Import("*", "path/to/alert.js")` just like we described earlier.
 
 - step 1: We specify the elements we wish to use. Here `*` means: "take everything that's been exported"
 - step 2: we set the path to our js library.
 - step 3: we create a let binding called `mylib` to map the js library.
-- step 4: we use the `jsNative` keyword to say that `mylib` is just a placeholder for the JavaScript native implementation.
+- step 4: we use the `nativeOnly` keyword to say that `mylib` is just a placeholder for the JavaScript native implementation.
 
 Now we can use this:
 
@@ -187,7 +195,7 @@ we could use the same method we used with `alert.js`:
     abstract drawBubble: (id:string) -> unit
 
   [<ImportAll("path/to/Canvas.js")>]
-  let mylib: ICanvas = jsNative
+  let mylib: ICanvas = nativeOnly
 
   mylib.drawSmiley "smiley" // etc..
 ```
@@ -250,7 +258,7 @@ You can use the `Emit` attribute to decorate a function. Every call to the funct
 open Fable.Core
 
 [<Emit("$0 + $1")>]
-let add (x: int) (y: string): string = jsNative
+let add (x: int) (y: string): string = nativeOnly
 
 let result = add 1 "2"
 ```
@@ -260,19 +268,19 @@ When you don't know the exact number of arguments you can use the following synt
 ```fsharp
 type Test() =
     [<Emit("$0($1...)")>]
-    member __.Invoke([<ParamArray>] args: int[]): obj = jsNative
+    member __.Invoke([<ParamArray>] args: int[]): obj = nativeOnly
 ```
 
 It's also possible to pass syntax conditioned to optional parameters:
 
 ```fsharp
 type Test() =
     [<Emit("$0[$1]{{=$2}}")>]
-    member __.Item with get(): float = jsNative and set(v: float): unit = jsNative
+    member __.Item with get(): float = nativeOnly and set(v: float): unit = nativeOnly
 
     // This syntax means: if second arg evals to true in JS print 'i' and nothing otherwise
     [<Emit("new RegExp($0,'g{{$1?i:}}')")>]
-    member __.ParseRegex(pattern: string, ?ignoreCase: bool): Regex = jsNative
+    member __.ParseRegex(pattern: string, ?ignoreCase: bool): Regex = nativeOnly
 ```
 
 The content of `Emit` will actually be parsed by [Babel](https://babeljs.io/) so it will still be validated somehow. However, it's not advised to abuse this method, as the code won't be checked by the F# compiler.
@@ -294,7 +302,7 @@ export default class MyClass {
     return this._value;
   }
 
-  set value( newValue ) {
+  set value(newValue) {
     this._value = newValue;
   }
 
@@ -332,7 +340,7 @@ type MyClassStatic =
   abstract getPI : unit-> float
 ```
 
-:::info
+:::{note}
 We could have used a class declaration with dummy implementations as we did with DataManager above, but you will find that in Fable bindings it's common to split the instance and static parts of a JS type in two interfaces to overcome some restrictions of the F# type system or to be able to deal with JS classes as values. In this case, by convention `Create` denotes the constructor.
 :::
 
@@ -342,7 +350,7 @@ Last but not least, let's import MyClass:
 
 ```fsharp
 [<ImportDefault("../public/MyClass.js")>]
-let MyClass : MyClassStatic = jsNative
+let MyClass : MyClassStatic = nativeOnly
 ```
 
 Now it's possible to use our JS class. Let's see the complete code:
@@ -359,7 +367,7 @@ type MyClassStatic =
   abstract getPI : unit-> float
 
 [<ImportDefault("../public/MyClass.js")>]
-let MyClass : MyClassStatic = jsNative
+let MyClass : MyClassStatic = nativeOnly
 
 let myObject = MyClass.Create(40, 42)
 
@@ -383,7 +391,7 @@ It's possible to combine the `Import` and `Emit` attributes. So we can import an
 ```fsharp
 [<ImportDefault("../public/MyClass.js")>]
 [<Emit("new $0({ value: $1, awesomeness: $2 })")>]
-let createMyClass(value: 'T, awesomeness: 'T) : MyClass<'T> = jsNative
+let createMyClass(value: 'T, awesomeness: 'T) : MyClass<'T> = nativeOnly
 ```
 
 ## Other special attributes
@@ -406,7 +414,7 @@ myLib.myMethod(String "test")
 ```
 
 ```js
-myLib.myMethod("test")
+myLib.myMethod("test");
 ```
 
 `Fable.Core` already includes predefined erased types which can be used as follows:
@@ -433,7 +441,7 @@ myMethod !^testValue
 myMethod !^2.3
 ```
 
-:::info
+:::{note}
 Please note erased unions are mainly intended for typing the signature of imported JS functions and not as a cheap replacement of `Choice`. It's possible to do pattern matching against an erased union type but this will be compiled as type testing, and since **type testing is very weak in Fable**, this is only recommended if the generic arguments of the erased union are types that can be easily told apart in the JS runtime (like a string, a number and an array).
 :::
 
@@ -476,7 +484,7 @@ myLib.myMethod(Vertical, Horizontal)
 
 ```js
 // js output
-myLib.myMethod("vertical", "Horizontal")
+myLib.myMethod("vertical", "Horizontal");
 ```
 
 ## Plain Old JavaScript Objects

docs-src/dotnet/compatibility.md

@@ -39,7 +39,7 @@ There is also support to convert between numeric types and to parse strings, che
 
 ### Caveats
 
-- All numeric types become JS `number` (64-bit floating type), except for `int64`, `uint64`, `bigint` and `decimal`. Check the [Numeric Types](numbers.html) section to learn more about the differences between .NET and JS.
+- All numeric types become JS `number` (64-bit floating type), except for `int64`, `uint64`, `bigint` and `decimal`. Check the [Numeric Types](numbers.md) section to learn more about the differences between .NET and JS.
 - Numeric arrays are compiled to [Typed Arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) when possible.
 - No bound checks for numeric types (unless you do explicit conversions like `byte 500`) nor for array indices.
 - `Regex` will always behave as if passed `RegexOptions.ECMAScript` flag (e.g., no negative look-behind or named groups).
@@ -69,9 +69,9 @@ MailboxProcessor  | fable-core/MailboxProcessor (limited support)
 
 ### Caveats II
 
-- Options are **erased** in JS (`Some 5` becomes just `5` in JS and `None` translates to `null`). This is needed for example, to represent TypeScript [optional properties](https://www.typescriptlang.org/docs/handbook/interfaces.html#optional-properties). However in a few cases (like nested options) there is an actual representation of the option in the runtime.
+- Options are **erased** in Python (`Some 5` becomes just `5` in Python and `None` translates to `null`). This is needed for example, to represent Python [optional properties](https://docs.python.org/3/library/typing.html#typing.Optional). However in a few cases (like nested options) there is an actual representation of the option in the runtime.
 - `Async.RunSynchronously` is not supported.
-- `MailboxProcessor` is single-threaded in JS and currently only `Start`, `Receive`, `Post` and `PostAndAsyncReply` are implemented (`cancellationToken` or `timeout` optional arguments are not supported).
+- `MailboxProcessor` is single-threaded in Python and currently only `Start`, `Receive`, `Post` and `PostAndAsyncReply` are implemented (`cancellationToken` or `timeout` optional arguments are not supported).
 
 ## Object Oriented Programming
 

docs-src/new-to-fsharp/let-keyword.md

@@ -53,8 +53,8 @@ Don't worry too much if you don't fully grasp the above code, the main goal of t
 
 The main differences that the `let` keyword in F# has from assignments in Python are:
 
-- In JavaScript one would use `let` to define a named variable, and its value can be reassigned which is not the case in F#.
-- In JavaScript `let` is scope bound, so one can declare a new variable with an already used name as long as it is in a different scope, in F# that can be done within the same scope.
+- In Python one would use an assignment to define a named variable, and its value can be reassigned which is not the case in F#.
+- In Python assignments are scope bound, so one can declare a new variable with an already used name as long as it is in a different scope, in F# that can be done within the same scope.
 
 ### References
 

docs-src/your-fable-project/project-file.md

@@ -3,7 +3,7 @@
 Unlike JS, F# projects require all sources to be listed **in compilation order** in an `.fsproj` file. This may look quite restrictive at first, but it does have [some advantages](https://fsharpforfunandprofit.com/posts/cyclic-dependencies/).
 Since an F# project takes its roots from the .NET ecosystem, we need to follow a few obligatory steps in order to add a file to an F# project.
 
-:::info
+:::{note}
 Many F# IDEs already provide commands to perform operations like creating a project or adding/removing a file. The steps below are only necessary if you want to do this manually.
 :::
 
@@ -51,7 +51,7 @@ For example, if we have have an app with two files, named `MyAwesomeFeature.fs`
 <ItemGroup>
 ```
 
-:::info
+:::{note}
 Please be aware that in F#, **file order is important.** For instance, if `App.fs` calls `MyAwesomeFeature.fs`, then you must place `MyAwesomeFeature.fs` above `App.fs`.
 :::