Update docs (#75)

* Start fixing

* Update docs

Author: dbrattli

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/_sources/
 docs-src/_build
 
 # PyBuilder

Build.fs

@@ -22,6 +22,10 @@ Target.create "Build" (fun _ ->
     run dotnet $"fable --exclude Fable.Core --lang Python --outDir {buildPath}" srcPath
 )
 
+Target.create "Docs" (fun _ ->
+    run poetry "run jb build docs-src --path-output docs" "."
+)
+
 Target.create "Run" (fun _ ->
     run dotnet "build" srcPath
 )
@@ -56,6 +60,9 @@ let dependencies = [
     "Build"
         ==> "Test"
 
+    "Build"
+        ==> "Docs"
+
     "Build"
         ==> "Pack"
 ]

Helpers.fs

@@ -76,6 +76,7 @@ let dotnet = createProcess "dotnet"
 
 let pytest = createProcess "pytest"
 let poetry = createProcess "poetry"
+let jupyterBook = createProcess "jb"
 
 let npm =
     let npmPath =

README.md

@@ -71,9 +71,10 @@ It contains example code for using Fable Python with:
 - [Femoto](https://github.com/Zaid-Ajaj/Femto)
 - [AsyncRx](https://github.com/dbrattli/AsyncRx)
 - [Fable.Aether](https://xyncro.tech/aether/)
-- [Fable.Giraffe](https://github.com/dbrattli/Fable.Giraffe)
-- [Fable.Logging](https://github.com/dbrattli/Fable.logging)
+- [Fable.Giraffe](https://github.com/dbrattli/Fable.Giraffe), port of Giraffe to Fable.Python
+- [Fable.Logging](https://github.com/dbrattli/Fable.logging), logging for Fable.Python
 - [Fable.Requests](https://github.com/Zaid-Ajaj/Fable.Requests)
+- [Fable.Jupyter](https://github.com/fable-compiler/Fable.Jupyter), Jupyter Notebook using Fable.Python
 - [Fable.SimpleJson.Python](https://github.com/Zaid-Ajaj/Fable.SimpleJson.Python)
 - [Fable.Sedlex](https://github.com/thautwarm/Fable.Sedlex)
 - [Feliz.ViewEngine](https://github.com/dbrattli/Feliz.ViewEngine)

docs-src/index.md

@@ -32,10 +32,10 @@ F# is already used on the server for web and cloud apps, and it's also used quit
 
 F# is a great choice to build beautiful apps that run in the browser. F# is:
 
-* Succinct with lightweight syntax
-* Robust with a great type system and pattern matching
-* Safe with immutability baked into the language
-* Supported by large companies (such as Microsoft and Jetbrains) and comes with commercial tooling support
+- Succinct with lightweight syntax
+- Robust with a great type system and pattern matching
+- Safe with immutability baked into the language
+- Supported by large companies (such as Microsoft and Jetbrains) and comes with commercial tooling support
 
 When compared with Python, F# is safer, more robust, and more pleasant to read and write.
 

docs-src/intro.md

@@ -4,21 +4,24 @@
 
 Hi!
 
-We're happy you decided to try Fable. Since F# is a language originally created for the .NET environment, Fable uses some tools that come from there.
+We're happy you decided to try Fable. Since F# is a language originally created for the .NET environment, Fable uses
+some tools that come from there.
 
-Don't panic! There is enough documentation to explain how the .NET tools integrate in your environment. And there are basically only two things you need to know:
+Don't panic! There is enough documentation to explain how the .NET tools integrate in your environment. And there are
+basically only two things you need to know:
 
 1. Fable uses F# project files (`.fsproj`) to list your F# code files and libraries.
-2. Fable uses NuGet to load F# libraries, which is the equivalent of NPM for the .NET environment
+2. Fable uses NuGet to load F# libraries, which is the equivalent of PyPI for the .NET environment
 
-Voilà. Nothing else. We'll come to explanations later in the docs. But we promise, there's nothing you won't understand right away. Apart from these facts, it's all JavaScript!
+Voilà. Nothing else. We'll come to explanations later in the docs. But we promise, there's nothing you won't understand
+right away. Apart from these facts, it's all JavaScript!
 
 **Welcome home!**
 
-- Fable transpiles F# to ES2015 JavaScript, Fable uses the great [Babel](https://babeljs.io/) tool for that.
-- Fable integrates with the popular [Webpack](https://webpack.js.org/). And it's not hard to use another bundler.
-- JS Dependencies are listed in your common `package.json` file.
-- Unit testing is available through [Fable.Mocha](https://github.com/Zaid-Ajaj/Fable.Mocha) (but you can use another test runner if you wish).
-- In most cases, building and running a Fable project only requires to call `npm install` and `npm start`.
+- Fable transpiles F# to Python 3.9.
+% - Fable integrates with the popular [Webpack](https://webpack.js.org/). And it's not hard to use another bundler.
+- Python Dependencies are listed in your common `pyproject.toml` file.
+- Unit testing is available through [pytest](https://docs.pytest.org) (but you can use another test runner if you wish).
+- In most cases, building and running a Fable project only requires to call `dotnet fable --lang py` and `poetry run python`.
 
-So since we're mainly using JavaScript tools, you won't be lost with Fable!
+So since we're using many of the well known Python tools, you won't be lost with Fable!

docs-src/introduction/py-users-read-this.md

@@ -1,6 +1,10 @@
 # Learning the language
 
-There are many resources available to learn F#. This section is only intended as a general guide targeted to JS developers, but is mainly contribution-driven and is still a work in progress. If you already know the basics of the language you can skip to [the next section](../2-steps/setup.html) or you can also check other sites and books about F# like:
+There are many resources available to learn F#. This section is only intended as a
+general guide targeted to Python developers, but is mainly contribution-driven and is still
+a work in progress. If you already know the basics of the language you can skip to [the
+next section](../2-steps/setup.html) or you can also check other sites and books about
+F# like:
 
 - [Tour of F#](https://docs.microsoft.com/en-us/dotnet/fsharp/tour)
 - [F# for Fun and Profit](https://fsharpforfunandprofit.com/)

docs-src/new-to-fsharp/learning-the-language.md

@@ -1,16 +1,19 @@
 # The let keyword
 
-`let` is the F# keyword used to bind any value to a name, it's used to bind the so called primitive types such as a `string` or an `integer`, to bind to a function or more complex structures such as arrays or records.
+`let` is the F# keyword used to bind any value to a name, it's used to bind the so called primitive types such as a
+`string` or an `integer`, to bind to a function or more complex structures such as arrays or records.
 
 Here's how you can bind a string to an identifier named `x`:
 
 ```fsharp
 let x = "some text"
 ```
 
-The above snippet would be considered a constant in some other languages such as JavaScript. In F# there's no `var` or `const` there's only `let` and since in F# every value is immutable by default, that snippet is the equivalent of a constant.
+The above snippet would be considered a variable in some other languages such as Python. In F# there's no `var` or
+`const` there's only `let` and since in F# every value is immutable by default, that snippet is the equivalent of a
+constant.
 
-Note that `let` in F# is different than `let` in JavaScript and this will be mentioned later on this page.
+Note that `let` in F# is different than assignment in Python and this will be mentioned later on this page.
 
 We're going to see more on functions later but here's how you can bind a function to an identifier named `add`:
 
@@ -19,11 +22,13 @@ let add x y =
     x + y
 ```
 
-In the above snippet a function that adds two integers is being bound to an identifier named `add` and then two values are being bound to the identifiers `x` and `y`.
+In the above snippet a function that adds two integers is being bound to an identifier named `add` and then two values
+are being bound to the identifiers `x` and `y`.
 
 ## Shadowing
 
-In F#, bindings are immutable by default which means that normally one _can't_ reassign a value to a named binding, rather, if you try to do so using `let` what will happen is that you'll shadow an existing binding.
+In F#, bindings are immutable by default which means that normally one _can't_ reassign a value to a named binding,
+rather, if you try to do so using `let` what will happen is that you'll shadow an existing binding.
 
 For instance, in the following example:
 
@@ -32,7 +37,9 @@ let x = "the answer"
 let x = 42
 ```
 
-In this case `x` is not being redefined nor its type is being changed from a `string` to an `int`, instead there are two different bindings with the same name `x` to different values. Of course, this example is not very useful because one binding is happening right after the other, but consider the following:
+In this case `x` is not being redefined nor its type is being changed from a `string` to an `int`, instead there are two
+different bindings with the same name `x` to different values. Of course, this example is not very useful because one
+binding is happening right after the other, but consider the following:
 
 ```fsharp
 let printName name =
@@ -47,14 +54,20 @@ let printName name =
 printName "John Doe"
 ```
 
-Don't worry too much if you don't fully grasp the above code, the main goal of that snippet is to demonstrate that the function `printName` expects an argument named `name` and in its body it defines another function `stripLastName` that also expects an argument `name`. Inside the scope of `stripLastName` the `name` argument is creating a new binding and thus shadowing the `name` argument received on the `printName` function. And that can be asserted by the two prints at the end of the `printName` function.
+Don't worry too much if you don't fully grasp the above code, the main goal of that snippet is to demonstrate that the
+function `printName` expects an argument named `name` and in its body it defines another function `stripLastName` that
+also expects an argument `name`. Inside the scope of `stripLastName` the `name` argument is creating a new binding and
+thus shadowing the `name` argument received on the `printName` function. And that can be asserted by the two prints at
+the end of the `printName` function.
 
 ## Comparing with Python
 
 The main differences that the `let` keyword in F# has from assignments in Python are:
 
-- 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.
+- 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/new-to-fsharp/let-keyword.md

@@ -18,8 +18,13 @@ The last point may sound complicated but it's only a matter of adding a couple o
 </ItemGroup>
 ```
 
-That's all it takes to make your library compatible with Fable! In order to publish the package to Nuget check [the Microsoft documentation](https://docs.microsoft.com/en-us/nuget/quickstart/create-and-publish-a-package-using-the-dotnet-cli) or alternatively you can also [use Fake](https://fake.build/dotnet-nuget.html#Creating-NuGet-packages).
+That's all it takes to make your library compatible with Fable! In order to publish the package to Nuget check [the
+Microsoft
+documentation](https://docs.microsoft.com/en-us/nuget/quickstart/create-and-publish-a-package-using-the-dotnet-cli) or
+alternatively you can also [use Fake](https://fake.build/dotnet-nuget.html#Creating-NuGet-packages).
 
 ## Testing
 
-It's a good idea to write unit tests for your library to make sure everything works as expected before publishing. The simplest way for that is to use a JS test runner like [Mocha](https://mochajs.org/), as in [this sample](https://github.com/fable-compiler/fable2-samples/tree/master/mocha). Or you can also use a library like [Fable.Mocha](https://github.com/Zaid-Ajaj/Fable.Mocha) containing more tools for Fable projects.
+It's a good idea to write unit tests for your library to make sure everything works as expected before publishing. The
+simplest way for that is to use a Python test runner like [pytest](https://pytest.org/), as in [this
+project](https://github.com/dbrattli/Fable.Giraffe).