You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/src/index.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -49,6 +49,8 @@ julia> servedocs()
49
49
50
50
Open a browser and go to `http://localhost:8000/` to see your docs being rendered; try modifying files (e.g. `docs/index.md`) and watch the changes being rendered in the browser.
51
51
52
+
You can also use LiveServer with both Documenter and [Literate.jl](https://github.com/fredrikekre/Literate.jl).
(_Thanks to [Fredrik Ekre](https://github.com/fredrikekre) and [Benoit Pasquier](https://github.com/briochemc) for their input; a lot of this section is drawn from an early prototype suggested by Fredrik._)
4
+
5
+
You've likely already seen how LiveServer could be used along with Documenter to have live updating documentation (see [`servedocs`](/man/functionalities/#servedocs-1) if not).
6
+
7
+
It is also easy to use LiveServer with both Documenter and [Literate.jl](https://github.com/fredrikekre/Literate.jl), a package for literate programming written by Fredrik Ekre that can convert julia script files into markdown.
8
+
This can be particularly convenient for documentation pages with a lot of code examples.
9
+
10
+
Only two steps are required to have this working (assuming you have already added Literate to your environment):
11
+
12
+
1. pick a folder structure
13
+
1. modify the `docs/make.jl` file to contain a line calling Literate
14
+
15
+
### Folder structure
16
+
17
+
There are effectively two recommended ways, pick whichever one you prefer.
18
+
In the first case, the script files `.jl` to be compiled by Literate are at the _same location_ as the output file so that you would have:
19
+
20
+
```
21
+
docs
22
+
└── src
23
+
├── index.jl
24
+
└── index.md
25
+
```
26
+
27
+
if you're happy with this, then you can jump to the [next step](#Modifying-the-make-file-1) to change the make file.
28
+
29
+
However you may not be happy with this, in particular if you have lots of such files and a mix of files which are generated by `Literate` and some which aren't, then typically you might prefer to keep all scripts in a separate folder.
30
+
You would just have to make sure that the output is properly redirected to `docs/src`.
31
+
Your folder structure would then look something like:
32
+
33
+
```
34
+
docs
35
+
├── lit
36
+
│ └── index.jl
37
+
└── src
38
+
└── index.md
39
+
```
40
+
41
+
The only thing you have to do in this case is to specify to `servedocs` where the "literate folder" is; this is a keyword argument and for the example above we would have:
42
+
43
+
```julia
44
+
servedocs(literate=joinpath("docs", "lit"))
45
+
```
46
+
47
+
### Modifying the make file
48
+
49
+
The only thing you have to do here is add a few lines to specify which files should be compiled by `Literate`.
50
+
Assuming you have taken the second path in the situation above, your `make.jl` file should look like:
51
+
52
+
```julia
53
+
using Documenter, Literate
54
+
55
+
src =joinpath(@__DIR__, "src")
56
+
lit =joinpath(@__DIR__, "lit")
57
+
58
+
for (root, _, files) ∈walkdir(lit), file ∈ files
59
+
splitext(file)[2] ==".jl"||continue
60
+
ipath =joinpath(root, file)
61
+
opath =splitdir(replace(ipath, lit=>src))[1]
62
+
Literate.markdown(ipath, opath)
63
+
end
64
+
65
+
makedocs(
66
+
sitename ="Test",
67
+
modules = [Test],
68
+
pages = ["Home"=>"index.md"]
69
+
)
70
+
```
71
+
72
+
If you were happy with the `.jl` and `.md` files being in the same location, simply replace the `lit = ` line by
73
+
74
+
```julia
75
+
lit = src
76
+
```
77
+
78
+
What the for loop does is simple: it loops over the files in the folder where it's likely to encounter `.jl` files and for those it encounters:
79
+
80
+
1. it retrieves the path to the file (`ipath`)
81
+
1. it constructs the output path in `docs/src` (`opath`)
82
+
1. it compiles the file `ipath` and saves the output at `opath`
83
+
84
+
## Complete example
85
+
86
+
Here's a step-by-step example to get started which should help put all the pieces together.
87
+
88
+
Let's start by creating a dummy repo
89
+
90
+
```julia-repl
91
+
pkg> generate testlit
92
+
julia> cd("testlit")
93
+
pkg> activate testlit
94
+
pkg> add Documenter Literate LiveServer
95
+
pkg> dev .
96
+
```
97
+
98
+
add a `docs/` folder with the appropriate structure so that the `testlit` folder ends up like
# if the file that was changed is the `make.jl` file, assume that maybe new files are # referenced and so refresh the vector of watched files as a result.
15
+
if fp == makejl
16
+
# it's easier to start from scratch (takes negligible time)
17
+
empty!(dw.watchedfiles)
18
+
scan_docs!(dw, literate)
29
19
end
30
-
# only trigger for changes appearing in `docs/src` otherwise a loop gets triggered
31
-
# changes from docs/src create change in docs/build which trigger a pass which
32
-
# regenerates files in docs/build etc...
33
-
if ismakejl ||occursin(joinpath("docs", "src"), fp)
20
+
ifsplitext(fp)[2] ∈ (".md", ".jl")
34
21
Main.include(makejl)
35
22
file_changed_callback(fp)
36
23
end
37
24
returnnothing
38
25
end
39
26
27
+
40
28
"""
41
-
scan_docs!(dw::SimpleWatcher)
29
+
scan_docs!(dw::SimpleWatcher, literate="")
42
30
43
31
Scans the `docs/` folder in order to recover the path to all files that have to be watched and add
44
-
those files to `dw.watchedfiles`. The function returns the path to `docs/make.jl`.
32
+
those files to `dw.watchedfiles`. The function returns the path to `docs/make.jl`. A list of
33
+
folders and file paths can also be given for files that should be watched in addition to the
0 commit comments