Safe Haskell	None
Language	Haskell2010

Thentos.Backend.Api.Docs.Common

Synopsis

Documentation

type RestDocs api = RestDocs' api :<|> api

class HasDocs api => HasDocExtras api where

Minimal complete definition

getCabalPackageName, getCabalPackageVersion, getTitle

Methods

getCabalPackageName

Arguments

:: Proxy api
-> ST	the name of the source package delivering the api

getCabalPackageVersion

Arguments

:: Proxy api
-> Version	the package version

getTitle :: Proxy api -> String

getIntros :: Proxy api -> [DocIntro]

getExtraInfo :: Proxy api -> ExtraInfo api

type HasFullDocExtras api = (HasDocs (RestDocs api), HasDocExtras (RestDocs api), HasForeign api, GenerateList (Foreign api))

restDocs :: forall api m. (Monad m, HasFullDocExtras api) => HttpConfig -> Proxy (RestDocs api) -> ServerT (RestDocs' api) m

restDocsMd :: forall api. (HasDocExtras (RestDocs api), HasForeign api, GenerateList (Foreign api)) => Proxy (RestDocs api) -> API

restDocsJs :: forall api. HasFullDocExtras api => Proxy (RestDocs api) -> ST

restDocsNg :: forall api. HasFullDocExtras api => Proxy (RestDocs api) -> ST

restDocsPurs :: forall api. HasFullDocExtras api => Proxy (RestDocs api) -> ST -> ST

prettyMimeRender :: API -> API

hackTogetherSomeReasonableOrder :: API -> API

The `servant-docs` package does offer a way to explicitly order intros (I'm not even sure if the implicit order is deterministic). This function allows you to write intros with titles of the form @@...@@, where ... contains section numbers composed of digits and dots. It will call sort on the list of intros then then chop of the section numbers off the intro titles. This way, the section numbers determine the order, and even if you don't provide section headings, everything will still work, and the intro list will be deterministic (even though not always meaningful).

The name of this function suggests that there may be a better way to solve this. (For one, the section numbers are ordered lexicographically, not numerically: compare "@@0.1@@" "@@0@@" == LT.)