This commit is contained in:
parent
aa2ff7b2f0
commit
2f3113f55d
11742 changed files with 1223940 additions and 0 deletions
|
|
@ -0,0 +1,11 @@
|
|||
Since odoc 3, pages can be installed in subdirectories of `doc/odoc-pages/`, so
|
||||
that odoc drivers (such as odig or the ocaml.org odoc driver) are able to
|
||||
recover the hierarchy.
|
||||
|
||||
For `dune`, this means that we need to provide the user a way to define the
|
||||
hierarchy they want for their mld files. Once the hierarchy is defined, `dune` needs to respect it by:
|
||||
|
||||
- Installing the files at the right location (for other drivers),
|
||||
- Driving `odoc` according to the hierarchy
|
||||
|
||||
This directory contains tests for the first point.
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 Example 1}
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 Example 2}
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 Index of examples}
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 summary}
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 index page}
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 Tutorial on foo}
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
(documentation
|
||||
(files
|
||||
(glob_files_rec
|
||||
(doc/* with_prefix .))))
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
(lang dune 3.18)
|
||||
|
||||
(package
|
||||
(name testing_mld)
|
||||
(allow_empty))
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
A useful pattern for documentation is to have a folder that contains only the
|
||||
documentation, and to include everything in it with:
|
||||
|
||||
$ cat dune
|
||||
(documentation
|
||||
(files
|
||||
(glob_files_rec
|
||||
(doc/* with_prefix .))))
|
||||
|
||||
The whole content of the doc folder is included as mld files/assets, replacing the doc/ prefix with "./"
|
||||
|
||||
Let's verify that:
|
||||
|
||||
$ dune build @install
|
||||
|
||||
We store the hierarchy of the doc/odoc-pages/ installed folder
|
||||
$ cd _build/install/default/doc/testing_mld/odoc-pages
|
||||
$ ls -R > ../../../../../../installed_hierarchy
|
||||
$ cd ../../../../../../
|
||||
We store the original hierarchy of the doc/ folder
|
||||
$ cd doc
|
||||
$ ls -R > ../source_hierarchy
|
||||
$ cd ../
|
||||
We compare both, they should be equal
|
||||
$ diff source_hierarchy installed_hierarchy
|
||||
|
||||
For the curious reader, here is the hierarchy:
|
||||
$ grep -v ".:" source_hierarchy # we remove ".:" for MacOS/Linux compatibility
|
||||
examples
|
||||
index.mld
|
||||
tutorial
|
||||
|
||||
example1
|
||||
example2
|
||||
index.mld
|
||||
summary.mld
|
||||
|
||||
index.mld
|
||||
|
||||
index.mld
|
||||
|
||||
tuto1.mld
|
||||
|
||||
Let's now verify that the install file is correct:
|
||||
$ cat _build/default/testing_mld.install
|
||||
lib: [
|
||||
"_build/install/default/lib/testing_mld/META"
|
||||
"_build/install/default/lib/testing_mld/dune-package"
|
||||
]
|
||||
doc: [
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/examples/example1/index.mld" {"odoc-pages/examples/example1/index.mld"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/examples/example2/index.mld" {"odoc-pages/examples/example2/index.mld"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/examples/index.mld" {"odoc-pages/examples/index.mld"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/examples/summary.mld" {"odoc-pages/examples/summary.mld"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/index.mld" {"odoc-pages/index.mld"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/tutorial/tuto1.mld" {"odoc-pages/tutorial/tuto1.mld"}
|
||||
]
|
||||
|
||||
Even though dune does not support yet building the doc with hierarchy, I can't
|
||||
resist building the doc to check what happens: currently, only top-level mld
|
||||
files are included in the doc generation.
|
||||
|
||||
$ dune build @doc
|
||||
Warning: Dune does not yet support building documentation for assets, and
|
||||
mlds in a non-flat hierarchy. Ignoring examples/example1/index.mld,
|
||||
examples/example2/index.mld, examples/index.mld, examples/summary.mld,
|
||||
tutorial/tuto1.mld.
|
||||
$ ls _build/default/_doc/_html/testing_mld
|
||||
db.js
|
||||
index.html
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
(documentation
|
||||
(mld_files) ; we avoid adding files twice, once through mld_files and once through files
|
||||
(files
|
||||
(glob_files
|
||||
(assets/* with_prefix .))
|
||||
; Assets in the source tree are in a subdirectory, but installed at the root of the doc
|
||||
(glob_files_rec examples/*) ; The examples in the source tree matches the one installed
|
||||
(glob_files
|
||||
(tuto*.mld with_prefix tutorial))
|
||||
; Tutorial files are in a subdir in the doc hierarchy
|
||||
(pkgname.mld as index.mld) ; pkgname.mld is renamed in order to be the index file
|
||||
notes.mld
|
||||
))
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 Example 1}
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 Example 2}
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 Index of examples}
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 summary}
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 Notes}
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 index page}
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 Tutorial on foo}
|
||||
|
|
@ -0,0 +1 @@
|
|||
{0 Tutorial on foo}
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
(lang dune 3.18)
|
||||
|
||||
(package
|
||||
(name testing_mld)
|
||||
(allow_empty))
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
The files field of the documentation stanza allows to control the hierarchy
|
||||
of documentation files
|
||||
|
||||
See doc/dune: here, the mld pages in tutorial/ will be installed in
|
||||
<page_root>/tutorial/tuto1/ while the ones in doc/ will be installed in
|
||||
<page_root>/ (where <page_root> is <opam switch root>/doc/<pkgname>/)
|
||||
|
||||
Let's verify that:
|
||||
|
||||
$ dune build @install
|
||||
$ ls -F _build/install/default/doc/testing_mld/odoc-pages
|
||||
examples/
|
||||
img1.png@
|
||||
img2.png@
|
||||
index.mld@
|
||||
notes.mld@
|
||||
tutorial/
|
||||
$ ls _build/install/default/doc/testing_mld/odoc-pages/tutorial/
|
||||
tuto1.mld
|
||||
tuto2.mld
|
||||
|
||||
$ cat _build/default/testing_mld.install
|
||||
lib: [
|
||||
"_build/install/default/lib/testing_mld/META"
|
||||
"_build/install/default/lib/testing_mld/dune-package"
|
||||
]
|
||||
doc: [
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/examples/example1/index.mld" {"odoc-pages/examples/example1/index.mld"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/examples/example2/index.mld" {"odoc-pages/examples/example2/index.mld"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/examples/index.mld" {"odoc-pages/examples/index.mld"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/examples/summary.mld" {"odoc-pages/examples/summary.mld"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/img1.png" {"odoc-pages/img1.png"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/img2.png" {"odoc-pages/img2.png"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/index.mld" {"odoc-pages/index.mld"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/notes.mld" {"odoc-pages/notes.mld"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/tutorial/tuto1.mld" {"odoc-pages/tutorial/tuto1.mld"}
|
||||
"_build/install/default/doc/testing_mld/odoc-pages/tutorial/tuto2.mld" {"odoc-pages/tutorial/tuto2.mld"}
|
||||
]
|
||||
|
||||
Even though dune does not support yet building the doc with hierarchy, I can't
|
||||
resist building the doc to check what happens: currently, only top-level mld
|
||||
files are included in the doc generation.
|
||||
|
||||
$ dune build @doc
|
||||
Warning: Dune does not yet support building documentation for assets, and
|
||||
mlds in a non-flat hierarchy. Ignoring examples/example1/index.mld,
|
||||
examples/example2/index.mld, examples/index.mld, examples/summary.mld,
|
||||
img1.png, img2.png, tutorial/tuto1.mld, tutorial/tuto2.mld.
|
||||
$ ls _build/default/_doc/_html/testing_mld
|
||||
db.js
|
||||
index.html
|
||||
notes.html
|
||||
Loading…
Add table
Add a link
Reference in a new issue