diff --git a/docs-src/2-steps/setup.md b/docs-src/2-steps/setup.md
new file mode 100644
index 0000000..a3c637c
--- /dev/null
+++ b/docs-src/2-steps/setup.md
@@ -0,0 +1,25 @@
+# Setup
+
+## Prerequisites
+
+In order to use Fable you will need the following tools:
+
+- [.NET Core SDK](https://dotnet.microsoft.com/) to work with F# files and dependencies
+- [Python](https://python.org/) to execute Python code
+- A Python package manager, like [poetry](https://python-poetry.org/)
+
+Having the above tools, you may consider using [Femto](https://fable.io/blog/2019/2019-06-29-Introducing-Femto.html) to
+ease package management.
+
+## Development tools
+
+Basically you will need an editor that lets you code in F# with features like hints on hover, autocomplete, syntax
+highlighting and so on... and there are many of them to suit your code styling!
+
+- [Visual Studio Code](https://code.visualstudio.com/) with [Ionide](http://ionide.io/)
+- [JetBrains Rider](https://www.jetbrains.com/rider/)
+- [Visual Studio For Windows](https://visualstudio.microsoft.com/)
+- [Visual Studio For Mac](https://visualstudio.microsoft.com/vs/mac/)
+- [Vim](https://www.vim.org/) with [F# bindings](https://github.com/fsharp/vim-fsharp)
+- [Emacs](https://www.gnu.org/software/emacs/)/[spacemacs](http://spacemacs.org/) with
+ [fsharp-mode](https://github.com/fsharp/emacs-fsharp-mode)
diff --git a/docs-src/2-steps/your-first-fable-project.md b/docs-src/2-steps/your-first-fable-project.md
new file mode 100644
index 0000000..8a2f6ef
--- /dev/null
+++ b/docs-src/2-steps/your-first-fable-project.md
@@ -0,0 +1,52 @@
+# Start a new project
+
+Now we're ready, let's start a new project using Fable!
+
+## Use a Fable template
+
+The easiest way to get started with Fable is to use a template (learn more about [dotnet
+templates](https://docs.microsoft.com/en-us/dotnet/core/tools/custom-templates#installing-a-template)). For a minimal
+Fable project, create and navigate to a new directory and run the following commands (first one is only needed if you
+haven't installed the template yet in your system).
+
+1. `dotnet new --install Fable.Template`
+2. `dotnet new fable`
+
+The rest of this document applies to Fable.Template. Alternatively, if you want specific examples or a more
+comprehensive template with more tooling and libraries installed, please check one of the following:
+
+- Clone the [Fable 3 samples](https://github.com/fable-compiler/fable3-samples) repository to learn how to use Fable
+ with different kinds of apps (browser, nodejs, testing, etc)
+- Build a [React](https://reactjs.org/) app in F# with [Feliz
+ template](https://zaid-ajaj.github.io/Feliz/#/Feliz/ProjectTemplate)
+- Write a frontend app fully in F# without JS dependencies with
+ [Sutil](https://davedawkins.github.io/Sutil/#documentation-installation)
+- Get up to speed with [SAFE Template](https://safe-stack.github.io/docs/quickstart/) which covers both the frontend and
+ backend sides of your app
+
+## Install dependencies
+
+**Python dependencies** are listed in the `pyproject.toml` file. You can run `poetry install`, which will download the
+needed packages to the `.venv` folder and create a lock file.
+
+**.NET dependencies** are listed in the `src/App.fsproj` file. You can install them by running `dotnet restore src`, but
+this is already automatically done by Fable.
+
+:::{note}
+Lock files (like `poetry.lock` if you're using poetry) should be committed to ensure reproducible builds whenever
+anybody clones your repo. For .NET dependencies you can create a lock file by using [Paket](https://fsprojects.github.io/Paket/).
+:::
+
+## Build & run the app
+
+Here we go. If you've already installed Python dependencies, just run `python app.py` (or `poetry run python app.py` if
+you are using poetry). After a few seconds, your web server app will be running in the background until you kill it.
+
+- You can access your project at [http://localhost:8080/](http://localhost:8080/) with your favorite browser.
+- The server is in “watch” mode. Each time you save an `.fs` F# source file, Fable rebuilds the project automatically.
+ If the build succeeds, you will see your changes in the browser without refreshing the page; if not, nothing changes
+ in the browser, and you can see the build errors in the server’s console output.
+
+:::{note} The `npm start` command is just an alias for `dotnet fable watch src --run webpack-dev-server`, check the
+"scripts" section of the `package.json` file. Please also check the `README.md` file shipped with the template to get
+up-to-date instructions. :::
diff --git a/docs-src/_toc.yml b/docs-src/_toc.yml
index 0a59ea3..cecdbb1 100644
--- a/docs-src/_toc.yml
+++ b/docs-src/_toc.yml
@@ -9,6 +9,8 @@ chapters:
- file: introduction/py-users-read-this
- file: new-to-fsharp/learning-the-language
- file: new-to-fsharp/let-keyword
+- file: 2-steps/setup
+- file: 2-steps/your-first-fable-project
- file: communicate/fable-from-py
- file: communicate/py-from-fable
- file: dotnet/compatibility
diff --git a/docs-src/your-fable-project/testing.md b/docs-src/your-fable-project/testing.md
index 329f295..af526a6 100644
--- a/docs-src/your-fable-project/testing.md
+++ b/docs-src/your-fable-project/testing.md
@@ -2,17 +2,22 @@
You can use all tools of the Python ecosystem.
-Several js libs already have a Fable binding:
+Several Python libs already have a Fable binding:
- mocha: [https://github.com/Zaid-Ajaj/Fable.Mocha](https://github.com/Zaid-Ajaj/Fable.Mocha)
- jest: [https://github.com/Shmew/Fable.Jester](https://github.com/Shmew/Fable.Jester)
-# Example with jest
+## Example with pytest
+
## Setup
-You should install js test runner :
+
+You should install pytest:
+
```sh
- npm install jest --save-dev
+poetry add --dev pytest
```
+
And Fable binding :
+
```sh
# nuget
dotnet add package Fable.Jester
@@ -21,7 +26,9 @@ And Fable binding :
```
## Write tests
+
Now, you can write your first test :
+
```fsharp
open Fable.Jester
@@ -31,16 +38,21 @@ Jest.describe("can run basic tests", fun () ->
)
)
```
+
See Jester documentation to more informations : [https://shmew.github.io/Fable.Jester/](https://shmew.github.io/Fable.Jester/)
## Run
-Before running the tests, you have to convert your project to JS, but you don't need to bundle with Webpack, because test runners generally prefer to have small files rather than a single big file. So we only need to run the Fable compiler and put the generated code in an output dir.
+
+Before running the tests, you have to convert your project to Python, but you don't need to bundle with Webpack, because
+test runners generally prefer to have small files rather than a single big file. So we only need to run the Fable
+compiler and put the generated code in an output dir.
```sh
dotnet fable src -o output
```
You should config Jest with a config file `jest.config.js` :
+
```js
module.exports = {
moduleFileExtensions: ['js'],
@@ -51,12 +63,14 @@ module.exports = {
transform: {}
};
```
+
`roots` should be equal to the `outDir` of the compiler.
`testMatch` indicate file pattern name with test.
`coveragePathIgnorePatterns`, `testEnvironment`, `transform` improve performance of runner.
You can read Jest doc to see more : [https://jestjs.io/docs/en/configuration](https://jestjs.io/docs/en/configuration)
Now, you can run then tests:
+
```sh
npx jest --config=jest.config.js
```
@@ -64,6 +78,7 @@ Now, you can run then tests:
Youhou! You can see the test result :)
You can specify this command on npm in `package.json` :
+
```json
{
"scripts": {
@@ -71,23 +86,28 @@ You can specify this command on npm in `package.json` :
},
}
```
+
And now run with a single command:
+
```sh
npm test
```
## Watch mode
+
Running tests each time is slow.
You can use the watch feature to take advantage of the compiler and runner cache, and run tests whenever a file changes.
Currently, Fable doesn't have official plugins for the different runners.
So you have to execute these two commands in parallel:
+
```sh
dotnet fable watch src -o output
npx jest --config=jest.config.js --watchAll
```
You add an npm script in `package.json` :
+
```json
{
"scripts": {
@@ -98,12 +118,15 @@ You add an npm script in `package.json` :
},
}
```
+
I use `npm-run-all` to run several commands in parallel. You should install with:
+
```sh
npm install --save-dev npm-run-all
```
Now, run
+
```sh
npm run-script watch-test
```
diff --git a/docs/2-steps/setup.html b/docs/2-steps/setup.html
new file mode 100644
index 0000000..0986bdc
--- /dev/null
+++ b/docs/2-steps/setup.html
@@ -0,0 +1,515 @@
+
+
+
+
+
Basically you will need an editor that lets you code in F# with features like hints on hover, autocomplete, syntax highlighting and so on… and there are many of them to suit your code styling!
The easiest way to get started with Fable is to use a template (learn more about dotnet templates). For a minimal Fable project, create and navigate to a new directory and run the following commands (first one is only needed if you haven’t installed the template yet in your system).
+
+
dotnetnew--installFable.Template
+
dotnetnewfable
+
+
The rest of this document applies to Fable.Template. Alternatively, if you want specific examples or a more comprehensive template with more tooling and libraries installed, please check one of the following:
+
+
Clone the Fable 3 samples repository to learn how to use Fable with different kinds of apps (browser, nodejs, testing, etc)
JS dependencies are listed in the package.json file. You can run npminstall, which will download the needed packages to the node_modules folder and create a lock file.
+
.NET dependencies are listed in the src/App.fsproj file. You can install them by running dotnetrestoresrc, but this is already automatically done by Fable.
+
+
Note
+
Lock files (like package-lock.json if you’re using npm) should be committed to ensure reproducible builds whenever anybody clones your repo. For .NET dependencies you can create a lock file by using Paket.
Here we go. If you’ve already installed JS dependencies, just run npmstart. After a few seconds, your web server app will be running in the background until you kill it.
The server is in “watch” mode. Each time you save an .fs F# source file, Fable rebuilds the project automatically. If the build succeeds, you will see your changes in the browser without refreshing the page; if not, nothing changes in the browser, and you can see the build errors in the server’s console output.
+
+
+
Note
+
The npmstart command is just an alias for dotnetfablewatchsrc--runwebpack-dev-server, check the “scripts” section of the package.json file. Please also check the README.md file shipped with the template to get up-to-date instructions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/communicate/fable-from-py.html b/docs/communicate/fable-from-py.html
index 4adb9ed..a496dbe 100644
--- a/docs/communicate/fable-from-py.html
+++ b/docs/communicate/fable-from-py.html
@@ -53,7 +53,7 @@
-
+
@@ -139,6 +139,16 @@