From 8a05685129c76204c96f886680bf8f0a1f246dd1 Mon Sep 17 00:00:00 2001
From: Paul-Elliot <peada@free.fr>
Date: Tue, 10 Sep 2024 13:02:06 +0200
Subject: [PATCH] Driver: Add instructions to test the pkg_args values

I could not make it run in cram tests: it has to be tested by hand.
---
 src/driver/test/pkg_args.t/run.t              | 25 +++++++++++++++
 .../test/pkg_args.t/test_odoc_driver/doc/dune |  1 +
 .../pkg_args.t/test_odoc_driver/doc/yo.mld    |  3 ++
 .../test/pkg_args.t/test_odoc_driver/dune     |  3 ++
 .../pkg_args.t/test_odoc_driver/dune-project  | 26 ++++++++++++++++
 .../test/pkg_args.t/test_odoc_driver/lib/dune |  3 ++
 .../test_odoc_driver/lib/test_odoc_driver.ml  |  1 +
 .../test_odoc_driver/odoc-config.sexp         |  2 ++
 .../test_odoc_driver/test_odoc_driver.opam    | 31 +++++++++++++++++++
 9 files changed, 95 insertions(+)
 create mode 100644 src/driver/test/pkg_args.t/run.t
 create mode 100644 src/driver/test/pkg_args.t/test_odoc_driver/doc/dune
 create mode 100644 src/driver/test/pkg_args.t/test_odoc_driver/doc/yo.mld
 create mode 100644 src/driver/test/pkg_args.t/test_odoc_driver/dune
 create mode 100644 src/driver/test/pkg_args.t/test_odoc_driver/dune-project
 create mode 100644 src/driver/test/pkg_args.t/test_odoc_driver/lib/dune
 create mode 100644 src/driver/test/pkg_args.t/test_odoc_driver/lib/test_odoc_driver.ml
 create mode 100644 src/driver/test/pkg_args.t/test_odoc_driver/odoc-config.sexp
 create mode 100644 src/driver/test/pkg_args.t/test_odoc_driver/test_odoc_driver.opam

diff --git a/src/driver/test/pkg_args.t/run.t b/src/driver/test/pkg_args.t/run.t
new file mode 100644
index 0000000000..809bada196
--- /dev/null
+++ b/src/driver/test/pkg_args.t/run.t
@@ -0,0 +1,25 @@
+Unfortunately, this cram test does not work due to interaction with opam and the
+sandboxing.
+
+Here is how to test the "pkg_args" feature, **by hand**.
+
+From the test_odoc_driver/ folder:
+
+  $ opam pin .
+
+Have a look at the `test_odoc_driver/odoc-config.sexp` file to see how it looks
+
+  $ cat test_odoc_driver/odoc-config.sexp
+  (packages brr)
+  (libraries brr brr.poke)
+
+From where you want (Most likely the root of the repo):
+
+  $ dune exec -- odoc_driver -p test_odoc_driver -p brr --link-grep page-yo
+  'odoc' 'link' '_odoc/test_odoc_driver/doc/page-yo.odoc' '-o' '_odoc/test_odoc_driver/doc/page-yo.odocl' '-I' '_odoc/test_odoc_driver/doc/' '-I' 'test_odoc_driver/lib/test_odoc_driver' '-P' 'brr:_odoc/brr/doc' '-P' 'test_odoc_driver:_odoc/test_odoc_driver/doc' '-L' 'brr.poke:_odoc/brr/lib/brr.poke' '-L' 'brr:_odoc/brr/lib/brr' '-L' 'test_odoc_driver:_odoc/test_odoc_driver/lib/test_odoc_driver' '--current-package' 'test_odoc_driver' '--enable-missing-root-warning'
+
+You can also check the references in the `yo` page resolves, by visiting the
+generated page!
+
+You can change the `odoc-config.sexp`, `opam upgrade test_odoc_driver` and rerun
+the driver to see how that affects the `-P` and `-L` values passed.
diff --git a/src/driver/test/pkg_args.t/test_odoc_driver/doc/dune b/src/driver/test/pkg_args.t/test_odoc_driver/doc/dune
new file mode 100644
index 0000000000..a24f8682f2
--- /dev/null
+++ b/src/driver/test/pkg_args.t/test_odoc_driver/doc/dune
@@ -0,0 +1 @@
+(documentation)
diff --git a/src/driver/test/pkg_args.t/test_odoc_driver/doc/yo.mld b/src/driver/test/pkg_args.t/test_odoc_driver/doc/yo.mld
new file mode 100644
index 0000000000..a1a946a0f5
--- /dev/null
+++ b/src/driver/test/pkg_args.t/test_odoc_driver/doc/yo.mld
@@ -0,0 +1,3 @@
+{0 Hey}
+
+Bli {!/brr/page-index} {!/brr.poke/Brr_poke}
\ No newline at end of file
diff --git a/src/driver/test/pkg_args.t/test_odoc_driver/dune b/src/driver/test/pkg_args.t/test_odoc_driver/dune
new file mode 100644
index 0000000000..e41bacc751
--- /dev/null
+++ b/src/driver/test/pkg_args.t/test_odoc_driver/dune
@@ -0,0 +1,3 @@
+(install
+ (files odoc-config.sexp)
+ (section doc))
diff --git a/src/driver/test/pkg_args.t/test_odoc_driver/dune-project b/src/driver/test/pkg_args.t/test_odoc_driver/dune-project
new file mode 100644
index 0000000000..e7f7cece84
--- /dev/null
+++ b/src/driver/test/pkg_args.t/test_odoc_driver/dune-project
@@ -0,0 +1,26 @@
+(lang dune 3.16)
+
+(name test_odoc_driver)
+
+(generate_opam_files true)
+
+(source
+ (github username/reponame))
+
+(authors "Author Name")
+
+(maintainers "Maintainer Name")
+
+(license LICENSE)
+
+(documentation https://url/to/documentation)
+
+(package
+ (name test_odoc_driver)
+ (synopsis "A short synopsis")
+ (description "A longer description")
+ (depends ocaml dune)
+ (tags
+  (topics "to describe" your project)))
+
+; See the complete stanza docs at https://dune.readthedocs.io/en/stable/reference/dune-project/index.html
diff --git a/src/driver/test/pkg_args.t/test_odoc_driver/lib/dune b/src/driver/test/pkg_args.t/test_odoc_driver/lib/dune
new file mode 100644
index 0000000000..7331968d97
--- /dev/null
+++ b/src/driver/test/pkg_args.t/test_odoc_driver/lib/dune
@@ -0,0 +1,3 @@
+(library
+ (public_name test_odoc_driver)
+ (name test_odoc_driver))
diff --git a/src/driver/test/pkg_args.t/test_odoc_driver/lib/test_odoc_driver.ml b/src/driver/test/pkg_args.t/test_odoc_driver/lib/test_odoc_driver.ml
new file mode 100644
index 0000000000..0547b3d0ee
--- /dev/null
+++ b/src/driver/test/pkg_args.t/test_odoc_driver/lib/test_odoc_driver.ml
@@ -0,0 +1 @@
+let x = 1
diff --git a/src/driver/test/pkg_args.t/test_odoc_driver/odoc-config.sexp b/src/driver/test/pkg_args.t/test_odoc_driver/odoc-config.sexp
new file mode 100644
index 0000000000..eea9f97186
--- /dev/null
+++ b/src/driver/test/pkg_args.t/test_odoc_driver/odoc-config.sexp
@@ -0,0 +1,2 @@
+(packages brr)
+(libraries brr brr.poke)
\ No newline at end of file
diff --git a/src/driver/test/pkg_args.t/test_odoc_driver/test_odoc_driver.opam b/src/driver/test/pkg_args.t/test_odoc_driver/test_odoc_driver.opam
new file mode 100644
index 0000000000..b296c11175
--- /dev/null
+++ b/src/driver/test/pkg_args.t/test_odoc_driver/test_odoc_driver.opam
@@ -0,0 +1,31 @@
+# This file is generated by dune, edit dune-project instead
+opam-version: "2.0"
+synopsis: "A short synopsis"
+description: "A longer description"
+maintainer: ["Maintainer Name"]
+authors: ["Author Name"]
+license: "LICENSE"
+tags: ["topics" "to describe" "your" "project"]
+homepage: "https://github.com/username/reponame"
+doc: "https://url/to/documentation"
+bug-reports: "https://github.com/username/reponame/issues"
+depends: [
+  "ocaml"
+  "dune" {>= "3.16"}
+  "odoc" {with-doc}
+]
+build: [
+  ["dune" "subst"] {dev}
+  [
+    "dune"
+    "build"
+    "-p"
+    name
+    "-j"
+    jobs
+    "@install"
+    "@runtest" {with-test}
+    "@doc" {with-doc}
+  ]
+]
+dev-repo: "git+https://github.com/username/reponame.git"