Fix daml-doc md

[samuel-williams-da]

Resolves #16474
Relevant question: https://discuss.daml.com/t/markdown-referencing-html-in-generated-doc/6222

Simply switches the generated md files and hoogle db to use .md on internal global anchors, when run with format=md

[samuel-williams-da]

Md fixes not tested, waiting on information for how to run hoogle with the generated file

[samuel-williams-da]

Confirmed hoogle points to md file when format=md is used.

[akrmn]

I don't know if this is common but I worry that someone might be generating the .md docs to then generate .html on their own pipeline; such a workflow would break, so I think this should be behind a new flag

[samuel-williams-da]

Fair point, I can add a --doc-ext flag that defaults to html?

[samuel-williams-da]

Seems like odd UX though to generate md docs and have it pointing to html, perhaps its worth somehow enquiring on whether people do this?

[samuel-williams-da]

Alternatively, I may add a little warning note if you use format=md without doc-ext=md. Do you think thats reasonable?

[akrmn]

yeah honestly I'm not sure what's the best for UX here. At least we don't seem to be using daml damlc docs to produce markdown in the DA repos (see search). The least disruptive would be to set --doc-ext=html by default, I think

[samuel-williams-da]

Yeah I believe our own docs are generated by calling the internals directly

[samuel-williams-da]

What do you think about the warning?

[akrmn]

Also, note that the paths with .html appear unused in the rst codepath, see here

[akrmn]

What do you think about the warning?
add a little warning note if you use format=md without doc-ext=md

hm yeah that sounds fine too

[samuel-williams-da]

Do we consider format=rst and doc-ext defined an error, given it will have no effect?

[akrmn]

Do we consider format=rst and doc-ext defined an error, given it will have no effect?

I think it's fine if it's just ignored in that case

[akrmn]

thanks for spotting this :)