Library companion site tools

Yes I’d like something like Tintin to be produced by Haddock. My main source of inspiration is ExDoc — ExDoc v0.36.1

I’ll have to play devils advocate here and say that there is no need to introduce any new syntax for docs and that the approach of a documentation module is probably the best one for multiple reasons:

  • Locality: I have the library docs next to the “user guide” and I can confidently reference symbols, modules, etc. All of this already works and has been extensively developed.
  • Compile-time checking: Documentation modules can be compiled to ensure that the exposed API is correct. With something like doctest I can even ensure that the examples are also correct. This compilation can be done conditionally using cabal flags
  • Single documentation language: There is no need to have separate languages for inline docs (Haddock) and tutorials (Markdown, rst, etc.).

Here I have an example cabal project where:

  • You can build the library only with cabal build
  • You can build the library + documentation modules with cabal build -fDocumentation
  • You can generate haddocks with cabal haddock -fDocumentation.

Example: HaskellSnippets/DocsExample at master · emlautarom1/HaskellSnippets · GitHub

I think the main is issue is that the Haddock docs are a bit opaque:

  • It does not easily show how to use haddock alongside cabal
  • It could have section comparing Markdown with Haddock for those who are new to the syntax

The solution IMO is to make haddock and cabal’s docs more modern by encouraging best practices, removing (or hiding) deprecated usages, and making assumptions about common cases (ex. invoking haddock in standalone fashion is quite rare).

6 Likes

One can put documentation in a public sublibrary, so that the main library avoids acquiring redundant dependencies.

Very few packages have such extensive documentation that it cannot be reasonably put into a single file, so I don’t really see a point of mdbook / readthedocs unless you have as massive documentation as Cabal or GHC.

3 Likes

Very few packages have such extensive documentation that it cannot be reasonably put into a single file, so I don’t really see a point of mdbook / readthedocs unless you have as massive documentation as Cabal or GHC.

I think a logically separate URL can be better than a single file, even for small projects, enough that it warrants some convention/standard and tools. Example usage, common recipes, getting started, and an explanation on the architecture are things I’d love to add to any of my small libraries and executables. Maybe not every project needs it, but if there’s more than 3-4 paragraphs to write for each, I think having separate semantic URLs is better for SEO (which turns to adoption and popularity). It’s also easier to share to others or maintain state between devices.

Right now for one of my libraries I just have multiple Markdown documents within the GitHub repository for the package, linked to each other: doc/README.md, doc/architecture.md, doc/examples.md. But discoverability is not great, I know some folks didn’t realise those docs existed until I linked to it.

I like the mdBook “hack” for Hackage, I just wish there was better visibility/discoverability for them from the Hackage page.
…I’ve just thought of something mildly cursed, which is to have a top-level module called “Documentation” (which would draw attention), upload HTML docs for it manually (instead of auto-generated Hackage ones) and somehow make it redirect to the mdBook page…

2 Likes