cvigilv · Sep 17, 2026 · Sep 15, 2026 · Sep 16, 2026
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -78,12 +78,13 @@ jobs:
             Pkg.develop(PackageSpec(path=pwd()))
             Pkg.instantiate()'
       - uses: julia-actions/julia-buildpkg@v1
-      - uses: julia-actions/julia-docdeploy@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - run: |
+      - name: Validate docstrings
+        run: |
           julia --project=docs -e '
             using Documenter: DocMeta, doctest
             using KEGGAPI
             DocMeta.setdocmeta!(KEGGAPI, :DocTestSetup, :(using KEGGAPI); recursive=true)
             doctest(KEGGAPI)'
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/README.md b/README.md
@@ -7,8 +7,7 @@
 [![code style: runic](https://img.shields.io/badge/code_style-%E1%9A%B1%E1%9A%A2%E1%9A%BE%E1%9B%81%E1%9A%B2-black)](https://github.com/fredrikekre/Runic.jl)
 [![DOI](https://zenodo.org/badge/667588694.svg)](https://doi.org/10.5281/zenodo.22282089)
 
-
-KEGGAPI.jl is a Julia package for accesing the Kyoto Encyclopedia of Genes and Genomes, striving to take advantage of the speed and flexibility that Julia offers and make it accessible to the bioinformatics and functional annotation communities.
+KEGGAPI.jl is a Julia client for the [Kyoto Encyclopedia of Genes and Genomes](https://www.kegg.jp/) REST API.
 
 ## KEGG usage terms
 
@@ -54,22 +53,22 @@ entries = ["hsa:$id" for id in 10458:10468]
 result = kegg_get(entries; request_delay = 0.5)
 ```
 
-The old `timeout` keyword remains available as a deprecated alias.
+The deprecated `timeout` keyword remains available as an alias for `request_delay`.
 
 ## Documentation
 
 - [Getting started](https://cvigilv.github.io/KEGGAPI.jl/dev/man/getting-started/)
 - [Examples](https://cvigilv.github.io/KEGGAPI.jl/dev/man/examples/)
 - [API reference](https://cvigilv.github.io/KEGGAPI.jl/dev/man/api/)
 
-Worked end-to-end use cases:
+Worked use cases:
 
 - [Case 1: From a UniProt ID to KEGG information](https://cvigilv.github.io/KEGGAPI.jl/dev/man/usecases/case1/)
 - [Case 2: EC reaction information in KEGG](https://cvigilv.github.io/KEGGAPI.jl/dev/man/usecases/case2/)
 - [Case 3: Identifying a compound in KEGG](https://cvigilv.github.io/KEGGAPI.jl/dev/man/usecases/case3/)
 - [Case 4: Target molecule information at KEGG](https://cvigilv.github.io/KEGGAPI.jl/dev/man/usecases/case4/)
 
-## Speed Tests
+## Benchmarks
 
 ![KEGGAPI.jl Benchmarks](benchmarking/benchmark.svg "KEGGAPI.jl Benchmarks")
 

diff --git a/benchmarking/README.md b/benchmarking/README.md
@@ -1,7 +1,7 @@
 # Benchmarking
 
-Compares `KEGGAPI.jl` against the other common KEGG REST clients — `KEGGREST`
-(R), `Bio.KEGG.REST` (Python) and raw `curl` — across the KEGG operations:
+This benchmark compares `KEGGAPI.jl`, `KEGGREST` for R, `Bio.KEGG.REST` for
+Python, and raw `curl` across these KEGG operations:
 
 | Operation | Query                          | Covered by            |
 |:----------|:-------------------------------|:----------------------|
@@ -14,18 +14,18 @@ Compares `KEGGAPI.jl` against the other common KEGG REST clients — `KEGGREST`
 | `Link`    | `link/pathway/hsa:10458`       | all                   |
 | `Ddi`     | `ddi/D00564`                   | KEGGAPI.jl, curl only |
 
-`ddi` has no wrapper in KEGGREST or Bio.KEGG.REST, so those interfaces simply
-have no bar for it in the figure. The `conv` case uses `ncbi-geneid` rather than
+KEGGREST and Bio.KEGG.REST do not wrap `ddi`, so the figure omits their bars for
+that operation. The `conv` case uses `ncbi-geneid` rather than
 `ncbi-proteinid` because Bio.KEGG.REST only recognises the legacy outside-database
 names (`ncbi-gi | ncbi-geneid | uniprot`) and rejects the newer ones.
 
 `KEGGAPI.jl`'s chunked `kegg_get` waits between requests to respect KEGG's rate
-limit. The Julia runner passes `request_delay = 0.0` because the runner already
-spaces its own calls and should not include that delay in its timings.
+limit. The Julia runner passes `request_delay = 0.0` because it already spaces
+calls and must not time the same delay twice.
 
-Each interface runs every operation inside a **single** process, so what is
-measured is per-call time rather than interpreter startup. A warm-up call is
-discarded before the measured replicates, and calls are spaced by `--pause`
+Each interface runs every operation in one process, which excludes interpreter
+startup from the measurements. The runner discards a warm-up call before the
+measured replicates and spaces calls by `--pause`
 seconds (default 0.4 s) to stay under KEGG's limit of 3 requests per second.
 
 ## Running
@@ -50,8 +50,8 @@ julia --project=benchmarking benchmarking/plot_benchmarks.jl
 
 ## Optional interfaces
 
-Only Julia and `curl` are required. Interfaces whose dependencies are missing
-are reported and skipped, so the run always completes. To include the others:
+Only Julia and `curl` are required. The script reports and skips interfaces
+whose dependencies are missing. To include the others:
 
 ```bash
 # R (KEGGREST via Bioconductor)
@@ -64,12 +64,12 @@ python3 -m venv /tmp/kegg_bench_venv
 
 ### Nix-provided R
 
-A nix R installs packages from source but does not expose its dependency paths
-to those builds, so CRAN/Bioconductor sources fail to link (`library not found
+A Nix-provided R installs packages from source but does not expose its dependency
+paths to those builds, so CRAN/Bioconductor sources fail to link (`library not found
 for -lintl`, `zlib.h not found`, `-lldap`, `-lkrb5`). Point `R_MAKEVARS_USER` at
-a Makevars supplying the paths — adjust the store hashes to match your system,
-which `otool -L $(R RHOME)/lib/libR.dylib` and `ls -d /nix/store/*<pkg>*` will
-tell you:
+a Makevars supplying the paths. Adjust the store hashes to match your system.
+Find them with `otool -L $(R RHOME)/lib/libR.dylib` and
+`ls -d /nix/store/*<pkg>*`:
 
 ```make
 GETTEXT  = /nix/store/...-gettext-0.22.5
@@ -89,13 +89,14 @@ R_MAKEVARS_USER=/path/to/Makevars \
   Rscript -e 'BiocManager::install("KEGGREST", ask = FALSE, update = FALSE)'
 ```
 
-Using `R_MAKEVARS_USER` keeps this out of `~/.R/Makevars`, so it applies only to
-the install. It is not needed to *run* the benchmark, only to build the packages.
+`R_MAKEVARS_USER` applies the settings only to this installation instead of
+writing them to `~/.R/Makevars`. The benchmark does not need it after the
+packages are built.
 
 ### Selecting interpreters
 
-The `JULIA`, `RSCRIPT` and `PYTHON` environment variables override which
-interpreter is used, which is how a virtualenv is selected:
+Set `JULIA`, `RSCRIPT`, or `PYTHON` to select an interpreter. For example, use
+`PYTHON` to select a virtual environment:
 
 ```bash
 PYTHON=/tmp/kegg_bench_venv/bin/python \
@@ -113,13 +114,12 @@ PYTHON=/tmp/kegg_bench_venv/bin/python \
 | `runners/bench_python.py`| Bio.KEGG.REST timings                               |
 | `runners/bench_curl.sh`  | Raw REST timings via `curl -w %{time_total}`        |
 
-Each runner prints `Function,Language,seconds` — one row per replicate — so it
-can also be run on its own, e.g.:
+Each runner prints one `Function,Language,seconds` row per replicate. Run an
+individual runner with:
 
 ```bash
 julia --project=benchmarking benchmarking/runners/bench_julia.jl 5 0.4
 ```
 
-> **Note:** results are dominated by network round-trip time to `rest.kegg.jp`
-> and will vary with location and server load. Compare interfaces within a
-> single run rather than across runs.
+Network round-trip time to `rest.kegg.jp` dominates these results. Compare
+interfaces within one run because location and server load vary between runs.
diff --git a/docs/make.jl b/docs/make.jl
@@ -8,9 +8,6 @@ makedocs(;
     authors = "Nicholas Geoffrion, Maria Victoria Aguilar Pontes, Carlos Vigil-Vásquez",
     repo = "https://github.com/cvigilv/KEGGAPI.jl/blob/{commit}{path}#{line}",
     sitename = "KEGGAPI.jl",
-    # `@example` blocks make live KEGG API calls at build time, so a transient
-    # KEGG outage or endpoint hiccup must not hard-fail the docs deploy.
-    warnonly = [:example_block],
     format = Documenter.HTML(;
         prettyurls = get(ENV, "CI", "false") == "true",
         canonical = "https://cvigilv.github.io/KEGGAPI.jl",

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -3,10 +3,9 @@ CurrentModule = KEGGAPI
 ```
 # KEGGAPI.jl
 
-A Julia interface for the [KEGG API](https://www.kegg.jp/kegg/rest/keggapi.html).
-The interface allows the functional annotation of genes, identification of metabolic processes
-and pathways, the exploration of reaction/pathway prevalence at different taxonomic levels and
-the identification of orthologous proteins for further analysis.
+KEGGAPI.jl is a Julia client for the [KEGG REST API](https://www.kegg.jp/kegg/rest/keggapi.html).
+It retrieves KEGG entries, sequences, images, database links, identifier conversions, and
+drug-drug interactions.
 
 ## KEGG usage terms
 
@@ -18,8 +17,7 @@ non-academic use.
 KEGGAPI.jl's MIT license covers only the Julia client code. It does not grant any rights to KEGG
 data or services.
 
-KEGGAPI.jl aims to support all KEGG API endpoints provided by the
-["KEGGREST"](https://bioconductor.org/packages/release/bioc/html/KEGGREST.html) package for R
-(Tenenbaum and maintainers, 2025) and the
-["Bio.KEGG.REST"](https://biopython.org/docs/1.75/api/Bio.KEGG.REST.html) submodule from
-Biopython for Python.
+Its endpoint coverage follows
+[KEGGREST](https://bioconductor.org/packages/release/bioc/html/KEGGREST.html) for R
+(Tenenbaum and maintainers, 2025) and
+[Bio.KEGG.REST](https://biopython.org/docs/1.75/api/Bio.KEGG.REST.html) for Python.
diff --git a/docs/src/man/examples.md b/docs/src/man/examples.md
@@ -1,49 +1,37 @@
 # Examples
 
-## KEGGAPI.conv
+## `kegg_conv`
 
-Examples analogous to [KEGG Conv](https://www.kegg.jp/kegg/rest/keggapi.html#conv)
-
-Querying the API for a simple conversion returns a list with:
-1. The API call
-2. The column headers of the call ( if the result is tabular )
-3. The data
-
-This allows to easily convert to a data frame:
+These examples call the [KEGG Conv](https://www.kegg.jp/kegg/rest/keggapi.html#conv)
+operation. `kegg_conv` returns the request URL, column names, and data in a
+`KeggTupleList`. Construct a `DataFrame` from `output.data` and
+`output.colnames`:
 
 ```@setup examples
 using KEGGAPI
 using DataFrames
 ```
 
 ```@example examples
-output = KEGGAPI.kegg_conv("eco", "ncbi-geneid"); 
-first(DataFrame(
-  output.data,
-  output.colnames
-), 5)
+output = KEGGAPI.kegg_conv("genes", "ncbi-geneid:948364")
+@assert output isa KEGGAPI.KeggTupleList
+DataFrame(output.data, output.colnames)
 ```
 
 ```@example examples
-output = KEGGAPI.kegg_conv("ncbi-geneid", "eco");
-first(DataFrame(
-  output.data,
-  output.colnames
-), 5)
+output = KEGGAPI.kegg_conv("ncbi-geneid", "eco:b0002")
+@assert output isa KEGGAPI.KeggTupleList
+DataFrame(output.data, output.colnames)
 ```
 
 ```@example examples
-output = KEGGAPI.kegg_conv("ncbi-proteinid", "hsa:10458+ece:Z5100");
-DataFrame(
-  output.data,
-  output.colnames
-)
+output = KEGGAPI.kegg_conv("ncbi-proteinid", ["hsa:10458", "ece:Z5100"])
+@assert output isa KEGGAPI.KeggTupleList
+DataFrame(output.data, output.colnames)
 ```
 
 ```@example examples
-output = KEGGAPI.kegg_conv("genes", "ncbi-geneid:948364");
-DataFrame(
-  output.data,
-  output.colnames
-)
+output = KEGGAPI.kegg_conv("genes", "uniprot:P0A6F9")
+@assert output isa KEGGAPI.KeggTupleList
+DataFrame(output.data, output.colnames)
 ```
diff --git a/docs/src/man/getting-started.md b/docs/src/man/getting-started.md
@@ -2,27 +2,31 @@
 
 ## Installation
 
-KEGGAPI.jl can be installed using the Julia package manager.
-From the Julia REPL, type `]` to enter the Pkg REPL mode and run
+From the Julia REPL, type `]` to enter the Pkg REPL and install KEGGAPI.jl:
 
 ```
 pkg> add KEGGAPI
 ```
 
 ## Usage
 
-To use KEGGAPI.jl, simply import the package:
+Load KEGGAPI.jl with `using`:
 
 ```@setup examples
 using KEGGAPI
 ```
 
-And use the interfaces to query the KEGG API. For example, to list all organisms (genomes) in KEGG:
+Each wrapper is named after its KEGG operation. This call lists all organisms in
+KEGG:
+
 ```@example examples
-result = KEGGAPI.kegg_list("genome");
+result = KEGGAPI.kegg_list("genome")
+@assert result isa KEGGAPI.KeggTupleList
+nothing # hide
 ```
-This returns a `KeggTupleList` object with the API call, column names and data. The data can
-accessed by indexing into the respective fields of the object:
+
+The result contains the request URL, column names, and data:
+
 ```@example examples
 result.url
 ```
@@ -43,4 +47,4 @@ KEGGAPI lets HTTP.jl exceptions propagate. An unsuccessful HTTP response throws
 `HTTP.Exceptions.TimeoutError`, respectively. See [`KEGGAPI.request`](@ref) for
 the low-level request contract.
 
-For more example usage, refer to the [examples](examples.md) page and the [API reference](api.md).
+See [Examples](examples.md) for more calls and [API reference](api.md) for the full interface.