damldocs: Backend for rendering docs to multiple pages. #2259
Conversation
ghost
force-pushed
the
damldocs-linked-project
branch
from
b37eb60 to
cb39474
Compare
| Hoogle -> const (renderLine "") -- not implemented (yet?) | ||
| Rst -> renderSimpleRst | ||
| Markdown -> renderSimpleMD | ||
| Html -> renderSimpleMD |
There was a problem hiding this comment.
Might be worth adding a comment that the conversion to Html is done in postProcessing. I first thought this was a typo 🙂
There was a problem hiding this comment.
Maybe this can be made clearer in code by something like
let (renderModule, postProcessing) = case ro_format of
Markdown -> (renderSimpleMD, id)
Html -> (renderSimpleMD, GFM.commonmarkToHtml [GFM.optUnsafe] [GFM.extTable])
...| -> T.Text -- ^ page body | ||
| -> T.Text | ||
| renderTemplate template pageTitle pageBody | ||
| = T.replace "__BODY__" pageBody |
There was a problem hiding this comment.
If this starts becoming more complex we might want to switch to some standard templating library, e.g., mustache. For now this is totally fine.
| case lookupAnchor env anchor of | ||
| Nothing -> escapeMd $ unTypename n | ||
| Just anchorLoc -> T.concat | ||
| [ "[" |
There was a problem hiding this comment.
Maybe add braces and parens helpers?
| @@ -23,38 +47,71 @@ newtype RenderEnv = RenderEnv (Set.Set Anchor) | |||
| -- Another possibly reason is that the anchor refers to a definition in another | |||
| -- package (and at the moment it's not possible to link accross packages). | |||
| renderAnchorAvailable :: RenderEnv -> Anchor -> Bool | |||
| renderAnchorAvailable (RenderEnv anchors) anchor = Set.member anchor anchors | |||
| renderAnchorAvailable RenderEnv{..} anchor = isJust (lookupAnchor anchor) | |||
There was a problem hiding this comment.
It looks like we aren’t using this anymore?
| ro_format = Html | ||
| ro_title = Nothing | ||
| ro_template = Nothing | ||
| renderDocs RenderOptions{..} docData |
There was a problem hiding this comment.
I'm not the biggest fan of using record wild cards to construct value when the proper record syntax would be good enough. I prefer something more explicit like
let opts = RenderOptions
{ ro_mode = RenderToFolder output
; ...
}| Hoogle -> const (renderLine "") -- not implemented (yet?) | ||
| Rst -> renderSimpleRst | ||
| Markdown -> renderSimpleMD | ||
| Html -> renderSimpleMD |
There was a problem hiding this comment.
Maybe this can be made clearer in code by something like
let (renderModule, postProcessing) = case ro_format of
Markdown -> (renderSimpleMD, id)
Html -> (renderSimpleMD, GFM.commonmarkToHtml [GFM.optUnsafe] [GFM.extTable])
...| case lookupAnchor env anchor of | ||
| Nothing -> escapeMd $ unTypename n | ||
| Just anchorLoc -> T.concat | ||
| [ "[" |
| -- rendered differently from an anchor that is external. Thus we can | ||
| -- handle every case correctly. | ||
| data AnchorLocation | ||
| = SamePage -- ^ anchor is in same file |
There was a problem hiding this comment.
| = SamePage -- ^ anchor is in same file | |
| = SameFile -- ^ anchor is in same file |
This PR provides the backend necessary to render docs to a folder, one page per module. It replaces the existing "one page per module" solution that already existed for rendering to HTML, which could not handle anchors across pages.
This PR also includes a couple of fixes for HTML output: anchor tags were not being rendered because of the CMark default options (which would strip out any raw HTML), so I changed that, and the default HTML template resulted in misinterpreted unicode since it didn't have a
<meta charset="utf-8">tag.I also added a Bazel target for generating standard library html docs in a tarball.
Future work / not done in this PR:
Hooking up the RendererOptions to the command line options for damldocs. Right now you can only render HTML across multiple files and everything else renders to a single file, which is the same as before.
Golden tests for multi-file rendering.