Add --format flag to spago docs

[elliotdavies]

Description of the change

Add a flag to spago docs to support different documentation formats. Fixes #294.

Running stack test on master seems to lead to about half the tests failing, so I can't verify that these changes haven't broken them further.

Checklist:

• Added the change to the "Unreleased" section of the changelog
• Added some example of the new feature to the README
• Added a test for the contribution (if applicable)

P.S.: the above checks are not compulsory to get a change merged, so you may skip them. However, taking care of them will result in less work for the maintainers and will be much appreciated 😊

[f-f]

Looks great! 👏

[elliotdavies]

@f-f Awesome, I just need to do a bit more work to specify an output file when you choose markdown | ctags | etags - otherwise by default the compiler just dumps to stdout. (You only get generated files when choosing html.)

[elliotdavies]

@f-f Actually, a question - in PureScript 0.13 the compiler will output HTML and MD to a generated-docs directory and ctags/etags to tags or TAGS files by default. In 0.12 it outputs HTML to generated-docs but any other option gets dumped to stdout.

What do you think is best for Spago to support? The defaults in 0.13 are fine, I think, but for anyone using 0.12 the stdout dump isn't going to be very useful (you can't even do spago docs --format ctags > tags because the tags file will end up including Spago's own logging). I could implement an --output option but purs doesn't support that in 0.12 so we'd have to implement it ourselves. Or we can just leave all the behaviour as it is.

[f-f]

@elliotdavies great point. Since we're still in 0.x of both Spago and Purs let's not worry too much about old Purs versions (i.e. it's fine unless we break them, which doesn't seem the case).
And once we fix #256 we'll have a --silent flag to silence Spago's own output, so we should be good anyways.

So I'd say let's go with 0.13 defaults

[elliotdavies]

@f-f OK! In that case I think this is ready to review 😄

[f-f]

Thank you @elliotdavies! 🙂