Allow user-set ids for xmldoc example nodes #704
Conversation
| @@ -78,6 +78,13 @@ module internal Utils = | |||
| module Html = | |||
| let sepWith s l = l |> List.sepWith (!! s) |> span [] | |||
|
|
|||
| type System.Xml.Linq.XElement with | |||
| member x.TryAttr (attr: string) = | |||
There was a problem hiding this comment.
I added this for convenience and then only used it in the new code, but I'd of course be willing to reuse it in the existing attribute fetches in this file if you like.
| let n = if id = 0 then "example" else "example-" + string id | ||
| rawData.[n] <- e.Value | ||
| let exampleId = | ||
| match e.TryAttr "id" with |
There was a problem hiding this comment.
tied to the question in the RFC change, what level of uniqueness should be enforced by tooling?
There was a problem hiding this comment.
Ideally fail if --strict is used, and warn otherwise
There was a problem hiding this comment.
I'm noodling around the implementation a bit here still for validation purposes: if the scope is just within a particular example then that's easy to do validation on, because we have all the examples locally, but at any other scope than that things get hard because we don't have that data available and/or we'd have to push the validation up a level...
There was a problem hiding this comment.
settled on duplicate within a member at the moment, but we could expand that to the type semi-easily if desired
|
@baronfel Thanks! Could you add a test please? |
| @@ -215,7 +215,7 @@ type HtmlRender(model: ApiDocModel) = | |||
|
|
|||
| for e in m.Comment.Examples do | |||
| h5 [Class "fsdocs-example-header"] [!! "Example"] | |||
| p [Class "fsdocs-example"] [embed e] | |||
| p [Class "fsdocs-example"; if e.Id.IsSome then Id e.Id.Value ] [embed e] | |||
There was a problem hiding this comment.
id's generated in the html now, yay
| comment.Examples | ||
| |> List.choose (fun x -> x.Id) | ||
| |> List.countBy id | ||
| for (id, count) in knownExampleIds do |
There was a problem hiding this comment.
this pass checks for duplicate example ids on a per-member basis
| else | ||
| printfn "%s(%d,%d): error: duplicate id for example '%s'" m.FileName m.StartLine m.StartColumn id | ||
| for (id, _count) in knownExampleIds do | ||
| if id.StartsWith "example-" then |
There was a problem hiding this comment.
this pass checks for missing example ids where we potentially inserted a dummy id
There was a problem hiding this comment.
then on same line as if please per style guide
Based on this discussion it seems like we should support user-defined ids for examples (for example to allow deep-linking to a specific example).