search

purescript / documentation

Documentation for the PureScript language, compiler, and tools.
Other
1.03k stars 300 forks source link

Discover doc format and site generation tool #53

Open chexxor opened 7 years ago

chexxor commented 7 years ago

Before moving to a tool, we should list the advantages we would gain by moving to such a system. Using a GitHub repo for docs, as we are now, is kinda nice for several reasons.

Pros/cons of GitHub repo, no special doc site:

Pros

Cons

owickstrom said on Twitter that he has recently moved from pandoc (?) to sphinx for Hyper's docs. We can view Hyper's doc site as a preview of a PureScript doc site built using Sphinx.

hdgarrood commented 7 years ago

I'm using Sphinx for my guide to the purescript numeric hierarchy and I'm really impressed with it. Also ReadTheDocs makes hosting dead simple, even easier than GH pages imo. The repo is https://github.com/hdgarrood/purescript-numeric-hierarchy-guide, but please don't share widely just yet as it's still at a very early stage.

chexxor commented 7 years ago

Some previous discussion about tools and directory/topic organization: https://github.com/purescript/purescript/issues/2455

owickstrom commented 7 years ago

I could help set up something with Sphinx. Haven't used ReadTheDocs, but it does indeed seem handy!

owickstrom commented 7 years ago

By the way, Pandoc is very useful for converting markdown to reStructured Text when moving to sphinx. 👌

chexxor commented 7 years ago

I copied a bunch of stuff from @owickstrom's repo to make this docs repo use Sphinx. It feels like a lot of config, but the make livehtml is pretty cool.

You can see what this repo would look like: https://github.com/chexxor/documentation/tree/try-sphinx The styles and html templates need work, if you do check out this branch.

I chose a directory structure to match the kubernetes docs, as I quite like theirs. Looks like their doc system is Jekyll, https://github.com/kubernetes/kubernetes.github.io/, which is interesting.

hdgarrood commented 7 years ago

That looks like a good starting point to me, but it seems we're now starting to talk about a fairly fundamental reorganization of the docs in addition to just switching to a different piece of software. Is it possible to consider these things separately?