Dhall-haskell: Multi-page generation respecting directory-tree structure vs package.dhall structure.

[german1608]

The dhall Prelude has the following package.dhall:

{ Bool = ./Bool/package.dhall
...
}

So we can reference the Bool _subpackage_ using either:

(./Prelude/package.dhall).Bool

or

(./Prelude/Bool/package.dhall)

But there may be the case that subpackages folders don't match the record field name in the package entrypoint. For instance, in

{ NameOverride = ./Subpackage/package.dhall
...
}

we can reference ./Subpackage/package.dhall either with

(./MyPackage/package.dhall).NameOverride

or

(./MyPackage/SubPackage/package.dhall)

My regard with this issue is: Shall we encourage users to organize their subpackages to match the record field on the package.dhall it references? Use first structure instead of the last one?

[Gabriel439]

@german1608: I think the tool should generate one page per source file in the directory tree, naming the pages after the files and not after record fields. There are a couple of reasons why I suggest this:

• The first reason why is that transitive imports of a file might not always be record fields. For example, they could be union alternatives:

  -- ./example.dhall
  < A : ./example/A.dhall | B : ./example/B.dhall >
  

  ... or they could nested in other ways:

  -- ./foo.dhall
  Optional ./bar.dhall
  

• The second reason is that having the HTML structure follow the directory structure gives the user more control over how the HTML is organized. They can group their definitions in one file if they want them to be within a single HTML page, or split them across multiple files if they want multiple pages.

[german1608]

Alright, and the docs shouldn't include non-exported files right?

For example, as this comment says, renderAs should not be included on the docs because although it appears on the directory tree it isn't exported on any package.dhall

[Gabriel439]

@german1608: I think it's fine if the docs include non-exported files. I think the documentation generator can still select a default entrypoint for browsing the documentation (typically package.dhall), but not everything necessarily needs to be reachable from that entrypoint.

[german1608]

@german1608: I think it's fine if the docs include non-exported files. I think the documentation generator can still select a default entrypoint for browsing the documentation (typically package.dhall), but not everything necessarily needs to be reachable from that entrypoint.

@Gabriel439 but if we include these non-reachable files, what is the purpose of the package.dhall file? Why doesn't the tool takes a directory as input instead?

[Gabriel439]

@german1608: Actually, maybe the tool should just take a directory as input instead

[german1608]

@Gabriel439 Yeah I agree. The cool thing I though about having the package.dhall file was that it will allow the tool to create an index for your package, adding some metadata about your package, but I think that that can come in another parameter and also that can come handy for a package manager instead of a doc generator

[sjakobi]

FWIW, I agree with what you've discussed above. :+1:

[Gabriel439]

I'll close as I think the original question was resolved