Add a convenience function to generate a servedocs+literate example (#89)

Author: tlienart

Project.toml

@@ -1,7 +1,7 @@
 name = "LiveServer"
 uuid = "16fef848-5104-11e9-1b77-fb7a48bbb589"
 authors = ["Jonas Asprion <jonas.asprion@gmx.ch", "Thibaut Lienart <tlienart@me.com>"]
-version = "0.3.4"
+version = "0.3.5"
 
 [deps]
 Crayons = "a8cc5b0e-0ffa-5ad4-8c14-923d3ee1735f"
@@ -14,6 +14,6 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
 Crayons = "^4.0.0"
-Documenter = "^0.23.0"
+Documenter = "^0.23, ^0.24"
 HTTP = "^0.8"
 julia = "^1.0.0"

docs/src/man/ls+lit.md

@@ -83,88 +83,20 @@ What the for loop does is simple: it loops over the files in the folder where it
 
 ## Complete example
 
-Here's a step-by-step example to get started which should help put all the pieces together.
-
-Let's start by creating a dummy repo
-
-```julia-repl
-pkg> generate testlit
-julia> cd("testlit")
-pkg> activate testlit
-pkg> add Documenter Literate LiveServer
-pkg> dev .
-```
-
-add a `docs/` folder with the appropriate structure so that the `testlit` folder ends up like
-
-```
-.
-├── Manifest.toml
-├── Project.toml
-├── docs
-│   ├── literate
-│   │   └── man
-│   │       └── pg1.jl
-│   ├── make.jl
-│   └── src
-│       ├── index.md
-│       └── man
-└── src
-    └── testlit.jl
-```
-
-where the file `pg1.jl` contains
-
-```julia
-# # Test literate
-
-# We can include some code like so:
-
-f(x) = x^5
-f(5)
-```
-
-the file `index.md` contains
-
-```
-# Test
-
-A link to the [other page](/man/pg1.md)
-```
-
-and the file `make.jl` contains
-
-```julia
-using Documenter, Literate
-
-src = joinpath(@__DIR__, "src")
-lit = joinpath(@__DIR__, "literate")
-
-for (root, _, files) ∈ walkdir(lit), file ∈ files
-    splitext(file)[2] == ".jl" || continue
-    ipath = joinpath(root, file)
-    opath = splitdir(replace(ipath, lit=>src))[1]
-    Literate.markdown(ipath, opath)
-end
-
-makedocs(
-    sitename = "testlit",
-    modules = [testlit],
-    pages = ["Home" => "index.md",
-             "Other page" => "man/pg1.md"]
-    )
-```
-
-Now `cd("testlit/")` and do
+The function `LiveServer.servedocs_literate_example` generates a directory which has the right structure that you can copy for your package.
+To experiment, do:
 
 ```julia-repl
+julia> using LiveServer
+julia> LiveServer.servedocs_literate_example("test_dir")
+julia> cd("test_dir")
 julia> servedocs(literate=joinpath("docs", "literate"))
 ```
 
-if you navigate to `localhost:8000` you should end up with
+if you then navigate to `localhost:8000` you should end up with
 
 ![](../assets/testlit.png)
 
-if you modify `testlit/docs/literate/man/pg1.jl` for instance writing `f(4)` it will be applied directly:
+if you modify `test_dir/docs/literate/man/pg1.jl` for instance writing `f(4)` it will be applied directly:
 
 ![](../assets/testlit2.png)

src/utils.jl

@@ -179,3 +179,68 @@ function example(; basedir="")
     isempty(basedir) && (basedir = pwd())
     cp(joinpath(dirname(dirname(pathof(LiveServer))), "example"), joinpath(basedir, "example"))
 end
+
+#
+# Generate example repo for servedocs
+#
+
+const INDEX_MD = raw"""
+    # Test
+    A link to the [other page](/man/pg1/)
+    """
+const PG1_JL  = raw"""
+    # # Test literate
+    # We can include some code like so:
+    f(x) = x^5
+    f(5)
+    """
+const MAKE_JL = raw"""
+    using Documenter, Literate
+    src = joinpath(@__DIR__, "src")
+    lit = joinpath(@__DIR__, "literate")
+    for (root, _, files) ∈ walkdir(lit), file ∈ files
+        splitext(file)[2] == ".jl" || continue
+        ipath = joinpath(root, file)
+        opath = splitdir(replace(ipath, lit=>src))[1]
+        Literate.markdown(ipath, opath)
+    end
+    makedocs(
+        sitename = "testlit",
+        pages = ["Home" => "index.md",
+                 "Other page" => "man/pg1.md"]
+        )
+    """
+
+"""
+servedocs_literate_example(dir="servedocs_literate_example")
+
+Generates a folder with the right structure for servedocs+literate example.
+You can then `cd` to that folder and use servedocs:
+
+```
+julia> using LiveServer
+julia> LiveServer.servedocs_literate_example()
+julia> cd("servedocs_literate_example")
+julia> servedocs(literate=joinpath("docs","literate"))
+```
+"""
+function servedocs_literate_example(dirname="servedocs_literate_example")
+    isdir(dirname) && rm(dirname, recursive=true)
+    mkdir(dirname)
+    # folder structure
+    src  = joinpath(dirname, "src")
+    mkdir(src)
+    write(joinpath(src, "$dirname.jl"), "module $dirname\n foo()=1\n end")
+    docs = joinpath(dirname, "docs")
+    mkdir(docs)
+    src = joinpath(docs, "src")
+    lit = joinpath(docs, "literate")
+    man = joinpath(lit, "man")
+    mkdir(src)
+    mkdir(lit)
+    mkdir(man)
+    write(joinpath(src, "index.md"), INDEX_MD)
+    write(joinpath(man, "pg1.jl"), PG1_JL)
+    write(joinpath(docs, "make.jl"), MAKE_JL)
+    return
+end

test/utils.jl

@@ -98,3 +98,17 @@ end
     @test isfile("example/index.html")
     cd(bk)
 end
+
+
+@testset "utils/servedocs_literate    " begin
+    bk = pwd()
+    tdir = mktempdir()
+    cd(tdir)
+    LiveServer.servedocs_literate_example("test")
+    @test isdir("test")
+    @test isfile(joinpath("test", "docs", "literate", "man",  "pg1.jl"))
+    @test isfile(joinpath("test", "docs", "src", "index.md"))
+    @test isfile(joinpath("test", "src", "test.jl"))
+    cd(bk)
+    rm(tdir, recursive=true)
+end