Contributing to the wiki/documentation

#1

Hello folks,

the GitHub wiki is a great source of documentation, unfortunately it seems like only the members with write access can update it. IIUC the GitHub solution is to use a dedicated project for the wiki content, e.g. dhall-lang/dhall-wiki with automation to sync the content to the dhall-lang.wiki.git. Another solution would be to move the wiki page into regular markdown file.

Could the wiki accept contribution through pull-request?

For example, I would like to propose a change to replace the unicode symbol with their ascii version, and perhaps suggest a new ‘Examples’ page with some practical content to help get started.

1 Like
#2

@tristanC: Another option I’ve been thinking about is replacing the wiki with documentation with documentation hosted on dhall-lang.org (similar to how, say, jsonnet’s documentation works). The reason I suggest this is that I’ve gotten a couple of complaints about the dhall-lang.org website linking to externally-hosted documentation on the GitHub wiki

If we did that then you’d be able to update documentation by a pull request against the dhall-haskell repository (which hosts the current website).

1 Like
#3

Actually, thinking more about this, the documentation doesn’t need to live in the dhall-haskell repository to be made available on dhall-lang.org. We can pretty easily have the nginx configuration which serves dhall-lang.org to support serving a subdirectory of the dhall-lang repository as static assets underneath docs.dhall-lang.org.

For reference, this is where we configure nginx for the website:

#4

What you are suggesting sounds great. I would be happy to help get that going though I am not familiar with nix or how the doc from dhall-haskell is rendered.

Also by self hosting the docs in dhall-lang.org you could get useful statistic about the popular documents.

1 Like
#5

@tristanC: The main thing you (or others) can help with is trying out various markdown-to-html documentation site generators. If we can agree on a particular one then I can set up the Nix logic to automatically generate docs.dhall-lang.org from the markdown files.

#6

I am used to sphinx-doc or getpelican but I guess it is better to use a haskell tool. I can have a look at Hakyll, unless others know something more suitable.

#7

@tristanC: We don’t have to use a Haskell tool. Any tool is fair game, thanks to Nix

1 Like
#8

Here is an initial proposal using sphinx: https://github.com/dhall-lang/dhall-lang/pull/826 . As noted in the commit message, I wonder if markdown is the right format for a comprehensive documentation website. I was able to import the wiki files almost as-is, but I had to use rst directive for the toc, which is less than ideal.

I also looked at hakyll, but to get a similar result (e.g. a navigable table of content) seems to require a lot of work and html templating… Ultimately i wasn’t able to make pandoc generate clickable section heading with anchor link, which i think is an important feature as it let us directly reference a particular doc section.

Hugo looks promising too, but it seems like we would also need to use html templating, thus it would be similar to the current proposal that is using inlined rst.

If using something other than markdown is an option, I think we would get better result using ReStructuredText (natively supported by sphinx) or with asciidoc.

2 Likes