Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] Documentation changes #2179

Merged
merged 3 commits into from
Nov 9, 2018
Merged

[WIP] Documentation changes #2179

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fbfbacb
Docs updates
sliepie Oct 29, 2018
6bd456a
Fix for code elements being too width
sliepie Nov 8, 2018
cccc836
doc fixes
sliepie Nov 8, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions help/content/assets/css/style.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,6 +242,12 @@ table.pre pre {
width: 100%;
}

table.pre code {
display: inline-block;
/* Width is set to 10px so the code block doesn't breakout of the pre element */
width: 10px;
}

table.pre td {
padding: 0px;
white-space: normal;
Expand Down
6 changes: 3 additions & 3 deletions help/markdown/fake-commandline.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Fake Build Options [build_opts]:
-f, --script <script.fsx>
The script to execute (defaults to `build.fsx`).
```
Please refer to the [Fake.Core.CommandLineParsing documentation](core-commandlineparsing.html) for a explanation of the synax.
Please refer to the [Fake.Core.CommandLineParsing](core-commandlineparsing.html) documentation for a explanation of the synax.

For now fake only supports the `run` and `build` subcommands which are basically equivalent to the Fake as you know it, but more are planned in the future. In general you should use the `run` subcommand in scripting when you use parameters, because it is safer in regards to adding options without breaking. Use `build` to have a more dense workflow in the command line

Expand All @@ -59,7 +59,7 @@ Currently Fake supports 4 verbosity levels:

### `--version`

Print FAKE version information.
Prints FAKE version information.

### `--help`

Expand Down Expand Up @@ -94,7 +94,7 @@ Display CLI help.

## Running Targets

Please refer to the [target module documentation](core-targets.html)
Please refer to the [Fake.Core.Target](core-targets.html) module documentation

For reference the CLI for the targets-module looks like this:

Expand Down
38 changes: 19 additions & 19 deletions help/markdown/fake-gettingstarted.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ FAKE is completely written in F# and all build scripts will also be written in F

There are various ways to install FAKE 5:

* Install FAKE as a global dotnet tool:
* Install FAKE as a global dotnet tool:
* To install FAKE globally, run:
<pre><code class="lang-bash">
dotnet tool install fake-cli -g
Expand All @@ -23,9 +23,9 @@ There are various ways to install FAKE 5:
dotnet tool install fake-cli --tool-path your_tool_path
</code></pre>

Use `--version` to specify the version of FAKE. See the [`global_tool` branch of `fake-bootstrap`](https://github.com/FakeBuild/fake-bootstrap/tree/global_tool) for ideas to bootstrap in your CI process.
Use `--version` to specify the version of FAKE. See the [`global_tool`](https://github.com/FakeBuild/fake-bootstrap/tree/global_tool) branch of `fake-bootstrap` for ideas to bootstrap in your CI process.

* Bootstrap via the [fake dotnet new template](fake-template.html). The template bootstraps FAKE and sets up a basic build-script.
* Bootstrap via the `fake dotnet new` [template](fake-template.html). The template bootstraps FAKE and sets up a basic build-script.
* To install the template run:
<pre><code class="lang-bash">
dotnet new -i "fake-template::*"
Expand All @@ -37,32 +37,32 @@ There are various ways to install FAKE 5:

See the [template](fake-template.html) page for more information.

* Install the 'fake' or 'fake-netcore' package for you system (currenty chocolatey).
* Install the 'fake' or 'fake-netcore' package for your system (currenty chocolatey).
Example `choco install fake`

* Use it as dotnet tool: Add `<DotNetCliToolReference Include="dotnet-fake" Version="5.*" />` to your dependencies and run `dotnet fake ...` instead of `fake ...`, see [this example](https://github.com/FakeBuild/fake-bootstrap/blob/master/dotnet-fake.csproj)
* Use it as a dotnet tool: Add `<DotNetCliToolReference Include="dotnet-fake" Version="5.*" />` to your dependencies and run `dotnet fake ...` instead of `fake ...`, see [this example](https://github.com/FakeBuild/fake-bootstrap/blob/master/dotnet-fake.csproj)


* Bootstrap via shell script (fake.cmd/fake.sh),
* Bootstrap via a shell script (fake.cmd/fake.sh),
see this [example project](https://github.com/FakeBuild/fake-bootstrap)
<div class="alert alert-warning">
<h5>WARNING</h5>
<p>These scripts have no versioning story. You either need to take care of versions yourself (and lock them) or your builds might break on major releases.</p>
</div>

* Bootstrap via paket `clitool`, basically the same as `DotNetCliToolReference` but managed via paket. See the [`paket_clitool` branch of `fake-bootstrap`](https://github.com/FakeBuild/fake-bootstrap/tree/paket_clitool) in particular the [build.proj](https://github.com/FakeBuild/fake-bootstrap/blob/paket_clitool/build.proj) file.
* Bootstrap via paket `clitool`, this is basically the same as `DotNetCliToolReference` but managed via paket. See the [`paket_clitool`](https://github.com/FakeBuild/fake-bootstrap/tree/paket_clitool) branch of `fake-bootstrap` in particular the [build.proj](https://github.com/FakeBuild/fake-bootstrap/blob/paket_clitool/build.proj) file.

## One note on Intellisense

Whenever you update the dependencies (part of the example) delete the `<script>.fsx.lock` file and re-run fake to update all files and intellisense!
Whenever you update the dependencies (part of the example), you need to delete the `<script>.fsx.lock` file and re-run fake to update all files and intellisense!

## Example - Compiling and building your .NET application

This example will guide you by adding a fake script to your existing .NET application.

### Getting started

Initially we need to create a file called `build.fsx` where our build-logic will have its home.
Initially we need to create a file called `build.fsx` where all our build-logic will reside.
Create a new file with Visual Studio or Visual Studio Code (with ionide) and paste the following content:

```fsharp
Expand All @@ -73,9 +73,9 @@ nuget Fake.Core.Target //"

This is all we need for now to declare that we need the `Fake.Core.Target` module and want to enable intellisense.

Now run `fake run build.fsx` to make fake prepare our environment. Now our IDE can load the dependencies and will have intellisense enabled (you might need to reopen the script file on some editors).
Now run `fake run build.fsx` to make fake prepare our environment. Now our IDE can load the dependencies and we will have intellisense enabled (you might need to reopen the script file on some editors).

Now that we have setup our basic environment to edit the script file we add our first target:
Now that we have setup our basic environment to edit the script file we can add our first target:

```fsharp
#r "paket:
Expand All @@ -93,7 +93,7 @@ Target.create "Default" (fun _ ->
Target.runOrDefault "Default"
```

As you can see the code is really simple. The few first lines (`nuget Fake.Core.Target` and `open Fake.Core`) load the fake modules we need and is vital for all build scripts to support creating and running targets. The `#load` line is optional but a good way to make the IDE aware of all the modules (for intellisense and IDE support)
As you can see the code is really simple. The first few lines (`nuget Fake.Core.Target` and `open Fake.Core`) load the fake modules we need and this is vital for all build scripts to support creating and running targets. The `#load` line is optional but a good way to make the IDE aware of all the modules (for intellisense and IDE support)

After this header the *Default* target is defined. A target definition contains two important parts. The first is the name of the target (here "Default") and the second is an action (here a simple trace of "Hello world").

Expand All @@ -114,9 +114,9 @@ nuget Fake.Core.Target //"
#load "./.fake/build.fsx/intellisense.fsx"
```

Now we remove the `build.fsx.lock` file and run `fake build` in order to restore the newly added `Fake.IO.FileSystem` module.
Now we need to remove the `build.fsx.lock` file and run `fake build` in order to restore the newly added `Fake.IO.FileSystem` module.

As we can now work with intellisense we can easily discover the various modules and functions in `Fake.IO`, for example the `Shell` module provides various functions you expect from regular shell scripting, but we use `Shell.CleanDir` which will ensure the given directory is empty by deleting everything within or creating the directory if required:
Since we now can rely on intellisense we can easily discover the various modules and functions in `Fake.IO`, for example the `Shell` module provides various functions you expect from regular shell scripting, we will use `Shell.cleanDir` which will ensure the given directory is empty by deleting everything within or creating the directory if required:


```fsharp
Expand Down Expand Up @@ -157,20 +157,20 @@ Target.runOrDefault "Default"

We introduced some new concepts in this snippet. At first we defined a global property called `buildDir` with the relative path of a temporary build folder.

In the `Clean` target we use the `Shell.CleanDir` task to clean up this build directory. As explained above this simply deletes all files in the folder or creates the directory if necessary.
In the `Clean` target we use the `Shell.cleanDir` task to clean up this build directory. As explained above this simply deletes all files in the folder or creates the directory if necessary.

In the dependencies section we say that the *Default* target has a dependency on the *Clean* target. In other words *Clean* is a prerequisite of *Default* and will be run before the execution of *Default*:
In the dependencies section we say that the *Default* target has a dependency on the *Clean* target. In other words *Clean* is a prerequisite of *Default* and will run before the *Default* target is executed:

![alt text](pics/gettingstarted/afterclean.png "We introduced a Clean target")

### Compiling the application

In the next step we want to compile our C# libraries, which means we want to compile all csproj-files under */src/app* with MSBuild.

Again we need some new module for this, namely `Fake.DotNet.MSBuild`.
Again we need a new module for this, namely `Fake.DotNet.MSBuild`.

Just like before add the required module on top via `nuget Fake.DotNet.MSBuild`, delete the `build.fsx.lock` file and run the script.
Now edit the script like this:
Now edit the script so it looks like this:

```fsharp
#r "paket:
Expand Down Expand Up @@ -278,7 +278,7 @@ This time we defined a new target "BuildTest" which compiles all C# projects bel

### Running the tests with NUnit

Now all our projects will be compiled and we can use FAKE's NUnit task in order to let NUnit test our assembly (again we need a new module `Fake.DotNet.Testing.NUnit`):
Now all our projects will be compiled and we can use FAKE's NUnit task in order to let NUnit test our assembly (we have to add a new module for this: `Fake.DotNet.Testing.NUnit`):

```fsharp
#r "paket:
Expand Down
12 changes: 5 additions & 7 deletions help/markdown/fake-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The Fake template bootstraps FAKE and sets up a basic build-script.

## Installation

Run
Run
<pre><code class="lang-bash">
dotnet new -i "fake-template::*"
</code></pre>
Expand All @@ -19,7 +19,7 @@ This will create a default `build.fsx` file, a `paket.dependencies` file used to
<pre><code class="lang-bash">
.\fake.cmd build
</code></pre>
to run your build. Have a look [this](fake-commandline.html) for the available command-line options. [This page](fake-gettingstarted.html#Example-Compiling-and-building-your-NET-application) additional information on how to use a build script.
to run your build. Have a look at the [fake commandline](fake-commandline.html) for the available command-line options. For additional information on how to use a build script, checkout the [getting started](fake-gettingstarted.html#Example-Compiling-and-building-your-NET-application) page.

## Options

Expand All @@ -29,7 +29,7 @@ Specifies the name of the generated build-script. Defaults to `build.fsx`.
### --bootstrap
Specifies your prefered way to bootstrap FAKE.

- `tool` (default) - Installs the FAKE dotnet sdk global tool into the `tool--path` folder
- `tool` (default) - Installs the FAKE dotnet sdk global tool into the `--tool-path` folder
- `project` - Creates a `build.proj` and uses `DotNetCliToolReference` to bootstrap FAKE
- `none` - Does not bootstrap FAKE. Use this if you want to use a global installation of FAKE

Expand All @@ -40,10 +40,8 @@ Specifies your prefered way to define the nuget packages used in your build:
- `inline` - Defines build dependencies inside the build script
- `none` - Use this if you already have a `paket.dependencies` in your folder

### --tool-path
Specifies the folder for the fake-cli tool. This parameter is only applicable when `tool` is used for bootstrapping. Defaults to `.fake`.
### --tool-path
Specifies the folder for the fake-cli tool. This parameter is only applicable when `tool` option is used for bootstrapping with `--bootstrap`. Defaults to `.fake`.

### --version
Specifies the version of FAKE to install. Defaults to `5.*`. This parameter is only applicable when either `tool` or `project` is used for bootstrapping.


40 changes: 20 additions & 20 deletions help/templates/indexpage.cshtml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
<div class="hero-body">
<div class="container">
<h2 class="title is-2 is-uppercase">Why use Fake?</h2>
<h3 class="subtitle is-3 is-uppercase">Fake was built on several key design principles ...</h3>
<h3 class="subtitle is-3 is-uppercase">Fake is built on several key design principles ...</h3>
</div>
</div>
</div>
Expand Down Expand Up @@ -123,14 +123,14 @@
#r "paket:
nuget Fake.Core.Target //"
#load "./.fake/build.fsx/intellisense.fsx"

open Fake.Core

// Default target
Target.create "Default" (fun _ ->
Trace.trace "Hello World from FAKE"
)

// start build
Target.runOrDefault "Default"
</code>
Expand All @@ -157,28 +157,28 @@
nuget Fake.IO.FileSystem
nuget Fake.Core.Target //"
#load "./.fake/build.fsx/intellisense.fsx"

open Fake.Core
open Fake.IO

// Properties
let buildDir = "./build/"

// Targets
Target.create "Clean" (fun _ ->
Shell.cleanDir buildDir
)

Target.create "Default" (fun _ ->
Trace.trace "Hello World from FAKE"
)

// Dependencies
open Fake.Core.TargetOperators

"Clean"
==> "Default"

// start build
Target.runOrDefault "Default"
</code>
Expand Down Expand Up @@ -206,38 +206,38 @@
nuget Fake.DotNet.MSBuild
nuget Fake.Core.Target //"
#load "./.fake/build.fsx/intellisense.fsx"

open Fake.IO
open Fake.IO.Globbing.Operators //enables !! and globbing
open Fake.DotNet
open Fake.Core

// Properties
let buildDir = "./build/"

// Targets
Target.create "Clean" (fun _ ->
Shell.cleanDir buildDir
)

Target.create "BuildApp" (fun _ ->
!! "src/app/**/*.csproj"
++ "src/*/*.target"
-- "src/*/*.vbproj"
|> MSBuild.runRelease id buildDir "Build"
|> Trace.logItems "AppBuild-Output: "
)

Target.create "Default" (fun _ ->
Trace.trace "Hello World from FAKE"
)

open Fake.Core.TargetOperators

"Clean"
==> "BuildApp"
==> "Default"

// start build
Target.runOrDefault "Default"
</code>
Expand All @@ -246,4 +246,4 @@

</div>
</section>
</div>
</div>