Integrate some of the work done in psc-pages by hdgarrood · Pull Request #1041 · purescript/purescript

hdgarrood · 2015-04-13T01:36:06Z

Some context:

We want to be able to render documentation in at least 3 different forms: Markdown (psc-docs), HTML (psc-pages), and as an input file for Hoogle (not really "documentation", but the process is very similar). The code I recently contributed to psc-pages splits the rendering into two stages, which makes it easy to render documentation in different forms in this way. In fact psc-pages can currently produce both HTML and ~~Markdown~~ Hoogle.
We want to fix bugs like Instances for private classes and types still appear in psc-docs output #747, and also only have to do it once.
We eventually want users to be able to run a tool locally which will generate HTML documentation and Hoogle input files, and then publish the results on the web.

It seems like the best way of accomplishing these 3 goals is to start looking at moving chunks of psc-pages into the library part of the purescript package. This PR is a step in this direction.

One small change I've made in this code that's not in the current psc-pages code, or even in the code in the open PR I have on psc-pages, is that the RenderedDeclaration etc types now have comments as String rather than Html - the code is the same, it just omits the final step transforming the comments into an HTML element. This allows us to output comments as Markdown, like psc-docs currently does, or as HTML.

Also, I decided to base off of 0.7-dev, since #747 is marked for 0.7.0, but I can change this easily if you'd like.

hdgarrood · 2015-04-13T01:46:10Z

Oh, also, to clarify - this code gets us part of the way towards fixing #747 but not all of the way there. It still needs to be wired up to psc-docs, and even then it doesn't handle every case. For example, if you have a module which:

defines and exports a type class
defines and does not export a data type
makes the data type an instance of the type class,

then the data type will still incorrectly appear in the list of instances for the type class. I think the solution would involve putting more information into the IntermediateDeclaration type in order to be able to check that none of the data types and type classes involved in an instance declaration are both defined in the current module, and also not exported.

hdgarrood · 2015-04-13T02:03:10Z

Oh, actually, maybe #747 should be fixed inside the compiler? This code already calls P.exportedDeclarations to get a filtered declaration list, so arguably instances containing private classes or types shouldn't be in that list at all?

Come to think of it, on a similar note, perhaps P.exportedDeclarations should additionally look deeper through the AST, and filter out things like unexported data constructors and type class members as well? As far as I can tell, the exportedDeclarations function is only used inside psci's completion, psc-docs, and psc-pages, so I don't think it would break anything to change that. This change would be really nice from the point of view of tools like psci and psc-pages, since we wouldn't have to pass a [P.DeclarationRef] around all the time and make a bunch of separate calls in different places to avoid accidentally including private things.

paf31 · 2015-04-13T02:24:04Z

Looks great, but I think I'd rather put the code under the psc-docs source directory.

Also, I'm not sure what the best plan of attack is w.r.t. 0.7-dev right now. Hopefully we can get it all merged soon, and then I could include this in the 0.7 release.

paf31 · 2015-04-13T02:24:49Z

Oh also, do you have plans to use this in psc-docs? I assume so, and that then psc-pages will just be subsumed by psc-docs?

hdgarrood · 2015-04-13T02:28:21Z

I had assumed that this code would also become part of the library section of the purescript package, which is why I included it in src, but come to think of it, I'm not sure it really needs to be used anywhere other than psc-docs - so I'll move it, as you say.

Yes, I was planning to use this in psc-docs, and then that should subsume psc-pages.

hdgarrood · 2015-04-13T02:31:01Z

Also, while I'm rearranging things like this, would you be ok with switching to Lucid for HTML generation?

hdgarrood · 2015-04-13T04:08:26Z

This now seems to work, with the code from psc-pages being used to render markdown output. Example: https://github.com/hdgarrood/purescript-sequences/blob/master/docs/Data.FingerTree.md

The main difference I've noticed is that the generated code now has some redundant brackets in type signatures, where it didn't have them before. (The HTML output in psc-pages has this too; I hadn't noticed!) I suppose we might want to use pattern-arrows to sort them out, in psc-docs/RenderedCode.hs?

Also, as it is currently, instances' docs (if any exist) are no longer displayed, based on the discussion we had in paf31/psc-pages#15, but if you only wanted that behaviour in psc-pages I can revert it easily.

hdgarrood · 2015-04-13T16:29:08Z

I've now tested this with purescript-sequences and purescript-random and I think it's good to go.

paf31 · 2015-04-13T16:30:57Z

Cool, I'll review this today. Could you please rebase it though?

paf31 · 2015-04-13T16:32:20Z

src/Language/PureScript/Docs/AsMarkdown.hs

Can the exports be refined at all?

Oh of course, sorry - will do.

No worries. I'm just trying to check off a few things like this with new modules.

hdgarrood · 2015-04-13T16:51:42Z

Sure, no problem. Should I squash all the commits?

paf31 · 2015-04-13T16:53:48Z

Yes please. I guess you would rebase from 0.7-dev right?

hdgarrood · 2015-04-13T17:12:40Z

Yeah, or I can rebase from master if that's easier

paf31 · 2015-04-13T17:16:53Z

No, 0.7-dev is good. I'll merge it there.

puffnfresh · 2015-04-13T17:40:50Z

I didn't know about psc-pages before. Great idea!

The Hoogle compatible stuff could be very useful 👍

paf31 · 2015-04-13T17:42:36Z

@puffnfresh Yep, the plan is to integrate Pursuit with Hoogle for @hdgarrood's GSOC project :)

hdgarrood · 2015-04-13T18:24:37Z

Rebased and squashed, and I've also added explicit export lists and Haddock docs where appropriate. I think this is good to go.

paf31 · 2015-04-13T18:33:53Z

src/Language/PureScript/Docs/RenderedCode/Render.hs

Maybe later we can try to unify this with the existing prettyPrintType function. We could maybe write a "plain text renderer".

I thought about doing this. Composing renderType with codeToString from the AsMarkdown module gets you most of the way there, there are just a couple of things that are not handled (eg Skolem).

Just a word of warning - pattern-arrows will spin if a case isn't handled, effectively adding parens forever, so you'll want to make sure your base cases are exhaustive :)

paf31 · 2015-04-13T18:34:11Z

Looks good. I'll merge this later when I do some work on 0.7.

hdgarrood · 2015-04-15T03:29:10Z

Arrghh, I messed up the rebase and somehow not all the changes I made to psc-docs were picked up. I'll redo them.

* Include a large chunk of code from psc-pages, allowing easier documentation output in multiple formats. * Rework psc-docs in order to use this new code. This makes psc-docs much simpler. * Partially fix #747, by putting instances in one chunk under their relevant data types and type classes. * Language.PureScript.Docs.RenderedCode now uses pattern-arrows in order to avoid unnecessary parentheses appearing in rendered code. * Remove unused code from psc-docs/Main.hs

hdgarrood · 2015-04-17T19:06:47Z

I did some more work building on this, and (unfortunately) I think it's now in a position where if this PR is merged, my other work won't apply cleanly. So I've submitted it in a separate PR instead (#1055).

paf31 reviewed Apr 13, 2015
View reviewed changes

hdgarrood mentioned this pull request Apr 15, 2015

Make exportedDeclarations filter everything #1045

Closed

hdgarrood mentioned this pull request Apr 17, 2015

Steps toward pursuit 2 #1055

Closed

hdgarrood closed this Apr 17, 2015

hdgarrood mentioned this pull request Apr 21, 2015

Steps toward pursuit 2 #1067

Merged

hdgarrood deleted the integrate-pages branch May 7, 2015 15:01

Conversation

hdgarrood commented Apr 13, 2015

Uh oh!

hdgarrood commented Apr 13, 2015

Uh oh!

hdgarrood commented Apr 13, 2015

Uh oh!

paf31 commented Apr 13, 2015

Uh oh!

paf31 commented Apr 13, 2015

Uh oh!

hdgarrood commented Apr 13, 2015

Uh oh!

hdgarrood commented Apr 13, 2015

Uh oh!

hdgarrood commented Apr 13, 2015

Uh oh!

hdgarrood commented Apr 13, 2015

Uh oh!

paf31 commented Apr 13, 2015

Uh oh!

paf31 Apr 13, 2015

Choose a reason for hiding this comment

Uh oh!

hdgarrood Apr 13, 2015

Choose a reason for hiding this comment

Uh oh!

paf31 Apr 13, 2015

Choose a reason for hiding this comment

Uh oh!

hdgarrood commented Apr 13, 2015

Uh oh!

paf31 commented Apr 13, 2015

Uh oh!

hdgarrood commented Apr 13, 2015

Uh oh!

paf31 commented Apr 13, 2015

Uh oh!

puffnfresh commented Apr 13, 2015

Uh oh!

paf31 commented Apr 13, 2015

Uh oh!

hdgarrood commented Apr 13, 2015

Uh oh!

paf31 Apr 13, 2015

Choose a reason for hiding this comment

Uh oh!

hdgarrood Apr 13, 2015

Choose a reason for hiding this comment

Uh oh!

paf31 Apr 13, 2015

Choose a reason for hiding this comment

Uh oh!

paf31 commented Apr 13, 2015

Uh oh!

hdgarrood commented Apr 15, 2015

Uh oh!

hdgarrood commented Apr 17, 2015

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants