Change default module to Main

.github/workflows/CI.yml

@@ -52,7 +52,7 @@ jobs:
       - name: Build docs
         run: |
           cd docs
-          julia --project -e 'using BooksDocs; BooksDocs.build()'
+          julia --project -e 'using BooksDocs; M = BooksDocs; BooksDocs.build()'
         env:
           GKS_ENCODING: "utf8"
           GKSwstype: "100"

docs/Project.toml

@@ -15,9 +15,11 @@ Latexify = "23fbe1c1-3f47-55db-b15f-69d7ec21a316"
 MCMCChains = "c7f686f2-ff18-58e9-bc7b-31028e88f75d"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
 
 [compat]
 Latexify = "0.15"
 MCMCChains = "4.9"
+Reexport = "1.1"

docs/contents/about.md

@@ -1,7 +1,6 @@
 # About {#sec:about}
 
-Basically, this package is a wrapper around [Pandoc](https://pandoc.org/){target="_blank"}; similar to [Bookdown](https://bookdown.org){target="_blank"}.
-Note that Pandoc does the heavy lifting and this package adds features on top.
+Similar to [Bookdown](https://bookdown.org){target="_blank"} this package is, basically, a wrapper around [Pandoc](https://pandoc.org/){target="_blank"}.
 For websites, this package allows for:
 
 - Building a website spanning multiple pages.
@@ -17,33 +16,79 @@ One of the main differences with Franklin.jl, Weave.jl and knitr (Bookdown) is t
 The benefit of this is that you can spawn two separate processes, namely the one to serve your webpages:
 
 ```jl
-serve_example()
+M.serve_example()
 ```
 
-and the one where you do the computations for your package `Foo`:
+and the one where you do the computations for your package:
 
-```jl
-generate_example()
+```
+$ julia --project -ie 'using Books'
+
+julia> gen()
+[...]
+Updating html
 ```
 
 This way, the website remains responsive when the computations are running.
 Thanks to LiveServer.jl and Pandoc, updating the page after changing text or code takes less than a second.
-Also, because the `serve` process does relatively few things, it doesn't often crash.
-A drawback of this decoupling is that you need to link your text to the correct computation in the Markdown file, whereas in other packages you would insert the code as a string.
+Also, because the `serve` process does relatively few things, it almost never crashes.
+
+As another benefit, the decoupling allows you to have more flexiblity in when you want to run what code.
+In combination with Revise.jl, you can quickly update your code and see the updated output.
+
+Finally, a big difference with this package and other packages is that you decide yourself what you want to show for a code block.
+For example, in R
+
+<pre>
+```{r, results='hide'}
+print("Hello, world!")
+```
+</pre>
+
+shows the code and not the output.
+Instead, in Books, you would write
+
+<pre>
+```jl
+sc(raw"""
+print("Hello, world!")
+"""
+)
+```
+</pre>
 
-The decoupling also allows the output, which you want to include, to be evaluated inside your package, see @sec:embedding-output.
-This means that you don't have to define all your dependencies in a `@setup` (Documenter.jl) or `# hideall` (Franklin.jl / Literate.jl) code block.
-(Granted, you could work your way around it by only calling methods inside a package.)
-The dependencies, such as `using DataFrames`, are available from your package.
-This provides all the benefits which Julia packages normally have, such as unit testing and live reloading via Revise.jl.
+which is displayed as
 
-As another benefit, all the code which you show in a book can be used via the function name.
-So, this avoids naming code blocks like "J3" and "J4", and allows users to load the code from your package and call the functions themselves.
-This has multiple benefits, namely
+```jl
+sc(raw"""
+print("Hello, world!")
+"""
+)
+```
+
+Here, `sc` is one of the convenience methods exported by Books.jl.
+Although this approach is more verbose in some cases, it is also much more flexible.
+In essence, you can come up with your own pre- or post-processing logic.
+For example, lets write
+
+<pre>
+```jl
+code = """
+    df = DataFrame(a=[1, 2], b=[3, 4])
+    Options(df, caption="A table", label=nothing)
+    """
+repeat(sco(code), 4)
+```
+</pre>
+
+which shows the code and output (`sco`) 4 times:
+
+```jl
+code = """
+    df = DataFrame(a=[1, 2], b=[3, 4])
+    Options(df, caption="A table", label=nothing)
+    """
+repeat(sco(code), 4)
+```
 
-1. it allows for explicitly using the output from one code block as input to another code block,
-1. it allows for demonstrating to the reader how to organize code (because, in general the tip is: use functions) _and_
-1. could save the reader from copy and pasting code.
 
-The latter point is due to the fact that the reader can load the package for the book and run the function.
-An example for points 1 and 2 is shown in @sec:function_code_blocks.