-
Notifications
You must be signed in to change notification settings - Fork 324
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
add micro tutorials / best practices about ocamlformat, odoc, adjust …
…editor setup tutorial (#1501)
- Loading branch information
Showing
10 changed files
with
109 additions
and
35 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,52 @@ | ||
--- | ||
id: "configuring-your-editor" | ||
title: "Configuring Your Editor" | ||
description: | | ||
How to set up Editor support for OCaml on VSCode, Vim and Emacs | ||
category: "Best Practices" | ||
--- | ||
|
||
# Configuring Your Editor | ||
|
||
OCaml has plugins for many editors, but the most actively maintained are for Visual Studio Code, Emacs, and Vim. | ||
|
||
## Visual Studio Code | ||
|
||
> **TL;DR** | ||
> | ||
> Install the VSCode extension `ocamllabs.ocaml-platform` and the packages `ocaml-lsp-server ocamlformat` in your opam switch. | ||
Install the [OCaml Platform Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=ocamllabs.ocaml-platform) from the Visual | ||
Studio Marketplace. | ||
|
||
The extension depends on OCaml LSP and ocamlformat. To install them in your switch, you can run: | ||
|
||
```shell | ||
$ opam install ocaml-lsp-server ocamlformat | ||
``` | ||
|
||
Upon first loading an OCaml source file, you may be prompted to select the | ||
toolchain in use. Pick the version of OCaml you are using, e.g., 4.14.0 | ||
from the list. Additional information is available by hovering over symbols in your program: | ||
|
||
![Visual Studio Code](/media/tutorials/vscode.png) | ||
|
||
**For Windows** | ||
1. If you used the Diskuv OCaml (DKML) installer you will need to: | ||
1. Go to `File` > `Preferences` > `Settings` view (or press `Ctrl ,`) | ||
2. Select `User` > `Extensions` > `OCaml Platform` | ||
3. **Uncheck** `OCaml: Use OCaml Env`. That's it! | ||
|
||
## Vim or Emacs | ||
|
||
Instead of using the LSP server, we can use Merlin directly. | ||
|
||
```shell | ||
$ opam install merlin | ||
``` | ||
|
||
When we installed Merlin above, instructions were printed on how to link Merlin with your editor. If you do not have them visible, just run this command: | ||
|
||
```shell | ||
$ opam user-setup install | ||
``` |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,26 @@ | ||
--- | ||
id: "formatting-your-code" | ||
title: "Formatting Your Code" | ||
description: | | ||
How to set up OCamlFormat to automatically format your code | ||
category: "Best Practices" | ||
--- | ||
|
||
# Formatting Your Code With OCamlFormat | ||
|
||
Automatic formatting with OCamlFormat requires an `.ocamlformat` configuration file at the root of the project. | ||
|
||
An empty file is accepted, but since different versions of OCamlFormat will vary in formatting, it | ||
is good practice to specify the version you're using. Running | ||
|
||
```shell | ||
$ echo "version = `ocamlformat --version`" > .ocamlformat | ||
``` | ||
|
||
creates a configuration file for the currently installed version of OCamlFormat. | ||
|
||
In addition to editor plugins that use OCamlFormat for automatic code formatting, Dune also offers a command to run OCamlFormat to automatically format all files from your codebase: | ||
|
||
```shell | ||
$ dune fmt | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
--- | ||
id: "generating-documentation" | ||
title: "Generating Documentation" | ||
description: | | ||
How to use odoc to generate documentation. | ||
category: "Best Practices" | ||
--- | ||
|
||
# Generating Documentation With Odoc | ||
|
||
The documentation rendering tool `odoc` generates documentation | ||
in the form of HTML, LaTeX, or man pages, | ||
from the docstrings and interfaces of the project's modules | ||
|
||
Dune can run `odoc` on your project to generate HTML documentation with this command: | ||
|
||
```shell | ||
$ dune build @doc | ||
|
||
# Unix or macOS | ||
$ open _build/default/_doc/_html/index.html | ||
|
||
# Windows | ||
$ explorer _build/default/_doc/_html/index.html | ||
``` |