Skip to content

Commit

Permalink
remove remaining references to tut
Browse files Browse the repository at this point in the history
  • Loading branch information
SethTisue committed Apr 12, 2021
1 parent 17cc7eb commit 5e8d3ae
Show file tree
Hide file tree
Showing 3 changed files with 4 additions and 65 deletions.
1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,5 +8,4 @@ _site
vendor/bundle
.idea/
/coursier
/tut-tmp/
.sass-cache/
66 changes: 3 additions & 63 deletions _overviews/contributors/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -392,7 +392,7 @@ jobs:

An important property of documentation is that the code examples should compile and behave as they
are presented. There are various ways to ensure that this property holds. One way, supported by
[tut](https://github.com/tpolecat/tut) and [mdoc](https://github.com/olafurpg/mdoc), is to actually
[mdoc](https://github.com/scalameta/mdoc), is to actually
evaluate code examples and write the result of their evaluation in the produced documentation.
Another way consists in embedding snippets of source code coming from a real module or example.

Expand Down Expand Up @@ -484,71 +484,11 @@ and behave as they are presented.

#### Using a Markdown Preprocessor

One approach consists in using a Markdown preprocessor, such as [tut](https://github.com/tpolecat/tut) or
[mdoc](https://github.com/olafurpg/mdoc). These tools read your Markdown source files, search for code fences,
One approach consists in using a Markdown preprocessor such as
[mdoc](https://github.com/scalameta/mdoc). These tools read your Markdown source files, search for code fences,
evaluate them (throwing an error if they don’t compile), and produce a copy of your Markdown files where
code fences have been updated to also include the result of evaluating the Scala expressions.

For instance, given the following `src/documentation/getting-started.md` file:

{% highlight markdown %}
# Getting Started

First, start with the following import:

```scala
import ch.epfl.scala.Example
```

Then, do nothing with something:

```scala
Example.doNothing(42)
```
{% endhighlight %}

The tut tool will produce the following Markdown file:

{% highlight markdown %}
# Getting Started

First, start with the following import:

```scala
scala> import ch.epfl.scala.Example
import ch.epfl.scala.Example
```

Then, do nothing with something:

```scala
scala> Example.doNothing(42)
res0: Int = 42
```
{% endhighlight %}

You can see that `tut` code fences have been replaced with `scala` code fences, and the result of
evaluating their content is shown, as it would look like from a REPL.

To enable tut, add the following line to your `project/plugins.sbt` file:

~~~ scala
addSbtPlugin("org.tpolecat" % "tut-plugin" % "0.6.10")
~~~

And apply the following changes to your `build.sbt` file:

{% highlight diff %}
+enablePlugins(TutPlugin)
-Paradox / sourceDirectory := sourceDirectory.value / "documentation"
+tutSourceDirectory := sourceDirectory.value / "documentation"
+Paradox / sourceDirectory := tutTargetDirectory.value
+makeSite := makeSite.dependsOn(tut).value
{% endhighlight %}

These changes add the `TutPlugin`, configure it to read sources from the `src/documentation` directory,
configure Paradox to read the output of tut, and make sure tut is run before the site is built.

#### Embedding Snippets

Another approach consists in embedding fragments of Scala source files that are part of a module which
Expand Down
2 changes: 1 addition & 1 deletion contribute.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ It's statically generated from [Markdown](https://en.wikipedia.org/wiki/Markdown

The markdown syntax being used supports [Maruku](https://github.com/bhollis/maruku) extensions, and has automatic syntax highlighting, without the need for any tags.

Additionally [tut](https://github.com/tpolecat/tut) is used during pull requests to validate Scala code blocks. To use this feature you must use the backtick notation as documented by tut. Note that only validation is done. The output files from tut are not used in the building of the tutorial. Either use `tut` or `tut:fail` for your code blocks.
Additionally [mdoc](https://github.com/scalameta/mdoc) is used during pull requests to validate Scala code blocks. To use this feature you must use the backtick notation as documented by mdoc. Note that only validation is done. The output files from mdoc are not used in the building of the tutorial. Use `mdoc` or `mdoc:fail` for your code blocks.

## Submitting Docs

Expand Down

0 comments on commit 5e8d3ae

Please sign in to comment.