Drop M keyword argument (#292)

README.md

@@ -12,18 +12,12 @@
     <a href="https://github.com/JuliaBooks/Books.jl/actions?query=workflow%3ACI+branch%3Amain">
         <img src="https://github.com/JuliaBooks/Books.jl/workflows/CI/badge.svg" alt="CI">
     </a>
-    <a href="https://books.huijzer.xyz">
+    <a href="https://huijzer.xyz/Books.jl/">
         <img src="https://img.shields.io/badge/Documentation-main-blue" alt="Documentation">
     </a>
     <a href="https://github.com/invenia/BlueStyle">
         <img src="https://img.shields.io/badge/Code%20Style-Blue-4495d1.svg" alt="Code Style Blue">
     </a>
-    <a href="https://github.com/SciML/ColPrac">
-        <img src="https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet" alt="Collaborative Practices for Community Packages">
-    </a>
-    <a href="https://books.pirsch.io">
-        <img src="https://img.shields.io/badge/Site-Analytics-blue" alt="Documentation analytics">
-    </a>
 </p>
 
 In a nutshell, this package is meant to generate books (or reports or dashboards) with embedded Julia output.
@@ -53,7 +47,7 @@ To install this package (Julia 1.6/1.7 on MacOS/Linux), use
 pkg> add Books
 ```
 
-See, the [documentation](https://books.huijzer.xyz) for more information.
+See, the [documentation](https://huijzer.xyz/Books.jl/) for more information.
 
 ### Windows
 

defaults/style.css

@@ -251,8 +251,8 @@ pre code {
   display: block;
   padding-top: 0px;
   padding-bottom: 0px;
-  margin-top: 0.3em;
-  margin-bottom: 0.3em;
+  margin-top: 0.0em;
+  margin-bottom: 0.0em;
 }
 
 pre {

docs/contents/about.md

@@ -8,6 +8,7 @@ For websites, this package allows for:
 - Cross-references from one web page to a section on another page.
 - Embedding dynamic output, while still allowing normal Julia package utilities, such as unit testing and live reloading (Revise.jl).
 - Showing code blocks as well as output.
+- Interacting with code from within the REPL.
 
 If you don't need to generate PDFs, then [Franklin.jl](https://github.com/tlienart/Franklin.jl){target="_blank"} is probably a better choice.
 To create single pages and PDFs containing code blocks, see [Weave.jl](https://github.com/JunoLab/Weave.jl){target="_blank"}.
@@ -16,7 +17,7 @@ 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
-M.serve_example()
+BooksDocs.serve_example()
 ```
 
 and the one where you do the computations for your package:
@@ -36,6 +37,10 @@ Also, because the `serve` process does relatively few things, it almost never cr
 As another benefit, the decoupling allows you to have more flexibility in when you want to run what code.
 In combination with Revise.jl, you can quickly update your code and see the updated output.
 
+Another reason why this package looks different than other packages is because this package has been aimed at a REPL workflow.
+Via the REPL, the package evaluates the code blocks inside `Main` by default.
+This provides easy access to the variables.
+
 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
 

docs/contents/demo.md

@@ -19,17 +19,26 @@ For embedding code, you can use the `jl` inline code or code block.
 For example, to show the Julia version, define a code block like
 
     ```jl
-    M.julia_version()
+    YourModule.julia_version()
     ```
 
 in a Markdown file.
 Then, in your package, define the method `julia_version()`:
 
 ```
-M.julia_version() = "This book is built with Julia $VERSION."
+julia_version() = "This book is built with Julia $VERSION."
 ```
 
-Next, ensure that you call `using Books; gen(; M)`, where `M = YourModule`.
+Next, call `using Books, MyPackage` and `gen()` to run all the defined in the Markdown files.
+If you prefer to be less explicit, you can call `gen(; M=YourModule)` to allow for:
+
+    ```jl
+    julia_version()
+    ```
+
+instead of `YourModule.julia_version()`.
+When passing your module `M` as keyword argument, `Books.jl` will evaluate all code blocks inside that module.
+
 Alternatively, if you work on a large project and want to only generate the output for one or more Markdown files in `contents/`, such as `index.md`, use
 
 ```language-julia
@@ -39,14 +48,14 @@ gen("index")
 Calling `gen` will place the text
 
 ```jl
-M.julia_version_example()
+BooksDocs.julia_version_example()
 ```
 
 at the right path so that it can be included by Pandoc.
 You can also embed output inline with single backticks like
 
 ```
-`jl julia_version()`
+`jl YourModule.julia_version()`
 ```
 
 or just call Julia's constant `VERSION` directly from within the Markdown file.
@@ -65,7 +74,7 @@ Note that it doesn't matter where you define the function `julia_version`, as lo
 To save yourself some typing, and to allow yourself to get some coffee while Julia gets up to speed, you can start Julia for your package with
 
 ```
-$ julia --project -ie 'using Books; using MyPackage; M = MyPackage'
+$ julia --project -ie 'using MyPackage'
 ```
 
 which allows you to re-generate all the content by calling
@@ -74,49 +83,47 @@ which allows you to re-generate all the content by calling
 julia> gen()
 ```
 
-To run this method automatically when you make a change in your package, ensure that you loaded [Revise.jl](https://github.com/timholy/Revise.jl) before loading your package and run
+To run this method automatically when you make a change in your package, ensure that you loaded [`Revise.jl`](https://github.com/timholy/Revise.jl) before loading your package and run
 
 ```language-julia
-entr(gen, ["contents"], [M])
+entr(gen, ["contents"], [MyPackage])
 ```
 
-where M is the name of your module.
-Which will automatically run `gen()` whenever one of the files in `contents/` changes or any code in the module `M`.
+Which will automatically run `gen()` whenever one of the files in `contents/` changes or any code in the `MyPackage` module.
 To only run `gen` for one file, such as `contents/my_text.md`, use:
 
 ```language-julia
-entr(["contents"], [M]) do
-    gen("my_text")
-end
+entr(() -> gen("my_text"), ["contents"], [MyPackage])
 ```
 
 Or, the equivalent helper function exported by `Books.jl`:
 
 ```language-julia
-entr_gen("my_text")
+entr_gen("my_text"; M=[MyPackage])
 ```
 
-With this, `gen("my_text")` will be called every time something changes in one of the files in the contents folder or when something changes in your module `M`.
-Note that you have to run this while `serve` is running in another terminal in the background.
-Then, your Julia code is executed and the website is automatically updated every time you change something in `content` or your module `M`.
+With this, `gen("my_text")` will be called every time something changes in one of the files in the contents folder or when something changes in `YourModule`.
+Note that you can run this while `serve` is running in another terminal in the background.
+Then, your Julia code is executed and the website is automatically updated every time you change something in `content` or `MyPackage`.
+Also note that `gen` is a drop-in replacement for `entr_gen`, so you can always add or remove `entr_` to run a block one time or multiple times.
 
 In the background, `gen` passes the methods through `convert_output(expr::String, path, out::T)` where `T` can, for example, be a DataFrame or a plot.
 To show that a DataFrame is converted to a Markdown table, we define a method
 
 ```jl
-@sc(M.my_table())
+@sc(BooksDocs.my_table())
 ```
 
 and add its output to the Markdown file with
 
     ```jl
-    M.my_table()
+    BooksDocs.my_table()
     ```
 
 Then, it will show as
 
 ```jl
-M.my_table()
+BooksDocs.my_table()
 ```
 
 where the caption and the label are inferred from the `path`.
@@ -129,14 +136,14 @@ Refer to @tbl:my_table with
 To show multiple objects, pass a `Vector`:
 
 ```jl
-@sco M.multiple_df_vector()
+@sco BooksDocs.multiple_df_vector()
 ```
 
 When you want to control where the various objects are saved, use `Options`.
 This way, you can pass a informative path with plots for which informative captions, cross-reference labels and image names can be determined.
 
 ```jl
-@sco M.multiple_df_example()
+@sco BooksDocs.multiple_df_example()
 ```
 
 To define the labels and/or captions manually, see @sec:labels-captions.
@@ -199,7 +206,7 @@ Possibly, the reasoning is that R Markdown needs to convert the output directly,
 To set labels and captions, wrap your object in `Options`:
 
 ```jl
-@sco(M.options_example())
+@sco(BooksDocs.options_example())
 ```
 
 which can be referred to with
@@ -213,7 +220,7 @@ It is also possible to pass only a caption or a label.
 This package will attempt to infer missing information from the `path`, `caption` or `label` when possible:
 
 ```jl
-M.options_example_doctests()
+BooksDocs.options_example_doctests()
 ```
 
 ## Obtaining function definitions {#sec:function_code_blocks}
@@ -223,32 +230,32 @@ So, instead of passing a string which `Books.jl` will evaluate, `Books.jl` can a
 For example, inside our package, we can define the following method:
 
 ```jl
-@sc(M.my_data())
+@sc(BooksDocs.my_data())
 ```
 
 To show code and output (sco) for this method, use the `@sco` macro.
 This macro is exported by Books, so ensure that you have `using Books` in your package.
 
     ```jl
-    @sco M.my_data()
+    @sco BooksDocs.my_data()
     ```
 
 This gives
 
 ```jl
-@sco M.my_data()
+@sco BooksDocs.my_data()
 ```
 
 To only show the source code, use `@sc`:
 
     ```jl
-    @sc M.my_data()
+    @sc BooksDocs.my_data()
     ```
 
 resulting in
 
 ```jl
-@sc M.my_data()
+@sc BooksDocs.my_data()
 ```
 
 To override options for your output, use the `pre` keyword argument of `@sco`:
@@ -276,39 +283,39 @@ Since we're using methods as code blocks, we can use the code shown in one code
 For example, to determine the mean of column A:
 
     ```jl
-    @sco M.my_data_mean(my_data())
+    @sco BooksDocs.my_data_mean(my_data())
     ```
 
 shows as
 
 ```jl
-@sco M.my_data_mean(my_data())
+@sco BooksDocs.my_data_mean(my_data())
 ```
 
-Or, we can show the output inline, namely `jl M.my_data_mean(my_data())`, by using
+Or, we can show the output inline, namely `jl BooksDocs.my_data_mean(my_data())`, by using
 
 ```
-`jl M.my_data_mean(my_data())`
+`jl BooksDocs.my_data_mean(my_data())`
 ```
 
 It is also possible to show methods with parameters.
 For example,
 
     ```jl
-    @sc M.hello("" )
+    @sc BooksDocs.hello("" )
     ```
 
 shows
 
 ```jl
-@sc M.hello("")
+@sc BooksDocs.hello("")
 ```
 
 Now, we can show
 
 ```jl
 scob("""
-M.hello("World")
+BooksDocs.hello("World")
 """)
 ```
 
@@ -344,55 +351,55 @@ Therefore, portable network graphics (PNG) images are also created and passed to
 Then, plotting works:
 
 ```jl
-@sco M.example_plot()
+@sco BooksDocs.example_plot()
 ```
 
 For multiple images, use `Options.(objects, paths)`:
 
 ```jl
-@sc M.multiple_example_plots()
+@sc BooksDocs.multiple_example_plots()
 ```
 
 Resulting in one `Plots.jl` (@fig:example_plot_2) and one `CairoMakie.jl` (@fig:example_plot_3) plot:
 
 ```jl
-M.multiple_example_plots()
+BooksDocs.multiple_example_plots()
 ```
 
 To change the size, change the resolution of the image:
 
 ```jl
-@sco M.image_options_plot()
+@sco BooksDocs.image_options_plot()
 ```
 
 And, for adjusting the caption, use `Options`:
 
 ```jl
-@sco M.combined_options_plot()
+@sco BooksDocs.combined_options_plot()
 ```
 
 or the caption can be specified in the Markdown file:
 
     ```jl
-    p = M.image_options_plot()
+    p = BooksDocs.image_options_plot()
     Options(p; caption="Label specified in Markdown.")
     ```
 
 ```jl
-p = M.image_options_plot()
+p = BooksDocs.image_options_plot()
 Options(p; caption="Label specified in Markdown.")
 ```
 
 \
 
 ```jl
-@sco M.plotsjl()
+@sco BooksDocs.plotsjl()
 ```
 
 This time, we also pass `link_attributes` to Pandoc (@fig:makie) to shrink the image width on the page:
 
 ```jl
-@sco M.makiejl()
+@sco BooksDocs.makiejl()
 ```
 
 ## Other notes
@@ -544,4 +551,5 @@ For example, this will show as:
        ```
 
     * another third level item
+    * and another