Merge pull request #8 from PumasAI/jk/readme-generation

Readme generation

.github/workflows/readme.yml

@@ -0,0 +1,30 @@
+name: Check up-to-date Readme
+on:
+  pull_request:
+    branches:
+      - master
+  push:
+    branches:
+      - master
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  readme:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+      - uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          version: pre-release
+      - name: Render readme
+        run: julia _readme/make.jl
+      - name: Succeed if there is no git diff output
+        run: git diff --exit-code
+

.gitignore

@@ -3,4 +3,5 @@ Manifest.toml
 /output
 /cache
 /docs/build
-.DS_Store
+.DS_Store
+.quarto

README.md

@@ -1,28 +1,28 @@
 # SummaryTables.jl
 
+
 <div align="center">
     <picture>
       <img alt="SummaryTables.jl logo" 
         src="/docs/src/assets/logo.png" width="150">
     </picture>
 </div>
 
-[![][docs-stable-img]][docs-stable-url]
-[![][docs-master-img]][docs-master-url]
-
-[docs-stable-img]: https://img.shields.io/badge/Docs-Stable-lightgrey.svg
-[docs-stable-url]: https://pumasai.github.io/SummaryTables.jl/stable/
-[docs-master-img]: https://img.shields.io/badge/Docs-Dev-blue.svg
-[docs-master-url]: https://pumasai.github.io/SummaryTables.jl/dev/
+[![](https://img.shields.io/badge/Docs-Stable-lightgrey.svg)](https://pumasai.github.io/SummaryTables.jl/stable/)
+[![](https://img.shields.io/badge/Docs-Dev-blue.svg)](https://pumasai.github.io/SummaryTables.jl/dev/)
 
-SummaryTables.jl is a Julia package for creating publication-ready tables in HTML, docx, LaTeX and Typst formats.
-Tables are formatted in a minimalistic style without vertical lines.
+SummaryTables.jl is a Julia package for creating publication-ready
+tables in HTML, docx, LaTeX and Typst formats. Tables are formatted in a
+minimalistic style without vertical lines.
 
-SummaryTables offers the `table_one`, `summarytable` and `listingtable` functions to generate pharmacological tables from Tables.jl-compatible data structures, as well as a low-level API to construct tables of any shape manually.
+SummaryTables offers the `table_one`, `summarytable` and `listingtable`
+functions to generate pharmacological tables from Tables.jl-compatible
+data structures, as well as a low-level API to construct tables of any
+shape manually.
 
 ## Examples
 
-```julia
+``` julia
 data = DataFrame(
     sex = ["m", "m", "m", "m", "f", "f", "f", "f", "f", "f"],
     age = [27, 45, 34, 85, 55, 44, 24, 29, 37, 76],
@@ -38,9 +38,9 @@ table_one(
 )
 ```
 
-![](/_readme/table_one.svg)
+![](README_files/figure-commonmark/cell-3-output-1.png)
 
-```julia
+``` julia
 data = DataFrame(
     concentration = [1.2, 4.5, 2.0, 1.5, 0.1, 1.8, 3.2, 1.8, 1.2, 0.2,
         1.7, 4.2, 1.0, 0.9, 0.3, 1.7, 3.7, 1.2, 1.0, 0.2],
@@ -62,18 +62,23 @@ listingtable(
 )
 ```
 
-![](/_readme/listingtable.svg)
+![](README_files/figure-commonmark/cell-4-output-1.png)
 
-```julia
+``` julia
 categories = ["Deciduous", "Deciduous", "Evergreen", "Evergreen", "Evergreen"]
 species = ["Beech", "Oak", "Fir", "Spruce", "Pine"]
-data = rand(4, 5)
+fake_data = [
+    "35m" "40m" "38m" "27m" "29m"
+    "10k" "12k" "18k" "9k" "7k"
+    "500yr" "800yr" "600yr" "700yr" "400yr"
+    "80\$" "150\$" "40\$" "70\$" "50\$"
+]
 labels = ["", "", "Size", Annotated("Water consumption", "Liters per year"), "Age", "Value"]
 
 body = [
     Cell.(categories, bold = true, merge = true, border_bottom = true)';
     Cell.(species)';
-    Cell.(data)
+    Cell.(fake_data)
 ]
 
 Table(hcat(
@@ -82,13 +87,22 @@ Table(hcat(
 ))
 ```
 
-![](/_readme/custom_table.svg)
+![](README_files/figure-commonmark/cell-5-output-1.png)
 
 ## Comparison with PrettyTables.jl
 
-[PrettyTables.jl](https://github.com/ronisbr/PrettyTables.jl/) is a well-known Julia package whose main function is formatting tabular data, for example as the backend to [DataFrames.jl](https://github.com/JuliaData/DataFrames.jl).
-PrettyTables supports plain-text output because it is often used for rendering tables to the REPL, however this also means that it does not support merging cells vertically or horizontally in its current state, which is difficult to realize with plain text.
-
-In contrast, SummaryTables's main purpose is to offer convenience functions for creating specific scientific tables which are out-of-scope for PrettyTables.
-For our desired aesthetics, we also needed low-level control over certain output formats, for example for controlling cell border behavior in docx, which were unlikely to be added to PrettyTables at the time of writing this package.
-
+[PrettyTables.jl](https://github.com/ronisbr/PrettyTables.jl/) is a
+well-known Julia package whose main function is formatting tabular data,
+for example as the backend to
+[DataFrames.jl](https://github.com/JuliaData/DataFrames.jl).
+PrettyTables supports plain-text output because it is often used for
+rendering tables to the REPL, however this also means that it does not
+support merging cells vertically or horizontally in its current state,
+which is difficult to realize with plain text.
+
+In contrast, SummaryTables’s main purpose is to offer convenience
+functions for creating specific scientific tables which are out-of-scope
+for PrettyTables. For our desired aesthetics, we also needed low-level
+control over certain output formats, for example for controlling cell
+border behavior in docx, which were unlikely to be added to PrettyTables
+at the time of writing this package.

_readme/Project.toml

@@ -0,0 +1,4 @@
+[deps]
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+SummaryTables = "6ce4ecf0-73a7-4ce3-9fb4-80ebfe887b60"
+Typst_jll = "eb4b1da6-20f6-5c66-9826-fdb8ad410d0e"

_readme/README.qmd

@@ -0,0 +1,122 @@
+---
+title: SummaryTables.jl
+engine: julia
+format: gfm
+execute: 
+  daemon: false
+---
+
+```{=html}
+<div align="center">
+    <picture>
+      <img alt="SummaryTables.jl logo" 
+        src="/docs/src/assets/logo.png" width="150">
+    </picture>
+</div>
+```
+
+[![](https://img.shields.io/badge/Docs-Stable-lightgrey.svg)](https://pumasai.github.io/SummaryTables.jl/stable/)
+[![](https://img.shields.io/badge/Docs-Dev-blue.svg)](https://pumasai.github.io/SummaryTables.jl/dev/)
+
+SummaryTables.jl is a Julia package for creating publication-ready tables in HTML, docx, LaTeX and Typst formats.
+Tables are formatted in a minimalistic style without vertical lines.
+
+SummaryTables offers the `table_one`, `summarytable` and `listingtable` functions to generate pharmacological tables from Tables.jl-compatible data structures, as well as a low-level API to construct tables of any shape manually.
+
+## Examples
+
+```{julia}
+#| output: false
+#| echo: false
+using SummaryTables, DataFrames, Statistics, Typst_jll
+
+Base.delete_method(only(methods(Base.show, (IO, MIME"text/html", SummaryTables.Table))))
+
+function Base.show(io::IO, ::MIME"image/png", tbl::SummaryTables.Table)
+    mktempdir() do dir
+        input = joinpath(dir, "input.typ")
+        open(input, "w") do io
+            println(io, """
+                        #set page(margin: 3pt, width: auto, height: auto, fill: white)
+                        #set text(12pt)
+                        """)
+            show(io, MIME"text/typst"(), tbl)
+        end
+        output = joinpath(dir, "output.png")
+        run(`$(typst()) compile $input $output`)
+        print(io, read(output, String))
+    end
+end
+```
+
+
+```{julia}
+data = DataFrame(
+    sex = ["m", "m", "m", "m", "f", "f", "f", "f", "f", "f"],
+    age = [27, 45, 34, 85, 55, 44, 24, 29, 37, 76],
+    blood_type = ["A", "0", "B", "B", "B", "A", "0", "A", "A", "B"],
+    smoker = [true, false, false, false, true, true, true, false, false, false],
+)
+
+table_one(
+    data,
+    [:age => "Age (years)", :blood_type => "Blood type", :smoker => "Smoker"],
+    groupby = :sex => "Sex",
+    show_n = true
+)
+```
+
+
+```{julia}
+data = DataFrame(
+    concentration = [1.2, 4.5, 2.0, 1.5, 0.1, 1.8, 3.2, 1.8, 1.2, 0.2,
+        1.7, 4.2, 1.0, 0.9, 0.3, 1.7, 3.7, 1.2, 1.0, 0.2],
+    id = repeat([1, 2, 3, 4], inner = 5),
+    dose = repeat([100, 200], inner = 10),
+    time = repeat([0, 0.5, 1, 2, 3], 4)
+)
+
+listingtable(
+    data,
+    :concentration => "Concentration (ng/mL)",
+    rows = [:dose => "Dose (mg)", :id => "ID"],
+    cols = :time => "Time (hr)",
+    summarize_rows = :dose => [
+        length => "N",
+        mean => "Mean",
+        std => "SD",
+    ]
+)
+```
+
+
+```{julia}
+categories = ["Deciduous", "Deciduous", "Evergreen", "Evergreen", "Evergreen"]
+species = ["Beech", "Oak", "Fir", "Spruce", "Pine"]
+fake_data = [
+    "35m" "40m" "38m" "27m" "29m"
+    "10k" "12k" "18k" "9k" "7k"
+    "500yr" "800yr" "600yr" "700yr" "400yr"
+    "80\$" "150\$" "40\$" "70\$" "50\$"
+]
+labels = ["", "", "Size", Annotated("Water consumption", "Liters per year"), "Age", "Value"]
+
+body = [
+    Cell.(categories, bold = true, merge = true, border_bottom = true)';
+    Cell.(species)';
+    Cell.(fake_data)
+]
+
+Table(hcat(
+    Cell.(labels, italic = true, halign = :right),
+    body
+))
+```
+
+## Comparison with PrettyTables.jl
+
+[PrettyTables.jl](https://github.com/ronisbr/PrettyTables.jl/) is a well-known Julia package whose main function is formatting tabular data, for example as the backend to [DataFrames.jl](https://github.com/JuliaData/DataFrames.jl).
+PrettyTables supports plain-text output because it is often used for rendering tables to the REPL, however this also means that it does not support merging cells vertically or horizontally in its current state, which is difficult to realize with plain text.
+
+In contrast, SummaryTables's main purpose is to offer convenience functions for creating specific scientific tables which are out-of-scope for PrettyTables.
+For our desired aesthetics, we also needed low-level control over certain output formats, for example for controlling cell border behavior in docx, which were unlikely to be added to PrettyTables at the time of writing this package.