Include images in documentation in generated content

[tymokvo]

Hello,

I have been trying to include visual content in library documentation. My use case is that I am working on a project that interfaces heavily with CAD workflows. So, it would be very valuable to be able to save snapshots of diagrams/drawings and include them in documentation that is then built into the static content by fsdocs.

I first asked on the fsharp slack for advice on the topic.

For example:

/// Pi is the ratio of circle's circumference to its diameter.
/// ![remote image](https://www.probability.ca/jeff/writing/pi1.jpg)
///
/// ![local image](images/pi.png)
let pi = 3.14159

Would result in an HTML tag like <img src="{root}content/img/pi.png" /> (or some other path in the output directory) in the documentation for that value.

It would be nice to be able to support embedded HTML, especially for resizing images. But I think supporting markdown images would be a good start if it is not already supported.

I have tried running fsdocs build --saveimages=all flag, but it seems to have no effect. This is possibly due to #683.

---

Looking through the markdown parser, it seems that this syntax should be supported to include an image:

https://github.com/fsprojects/FSharp.Formatting/blob/2efb355823b8311f91a06566c0a3de86037a590d/src/FSharp.Formatting.Markdown/MarkdownParser.fs#L479-L498

And looking through the BuildCommand, it seems that remote and local images should be supported:

https://github.com/fsprojects/FSharp.Formatting/blob/2efb355823b8311f91a06566c0a3de86037a590d/src/fsdocs-tool/BuildCommand.fs#L49-L71

Though, the imageSaverOpt value in processFile seems to only ever be passed into the Literate methods, which is what I assume the linked issue is in reference to.

[nhirschey]

If you want text to be interpreted as markdown you need to use (* … ) comments. See the docs about literate scripts for reference. https://fsprojects.github.io/FSharp.Formatting/literate.html

If it’s not inside a (* ) comment it’s not parsed as markdown.

(** Pi is the ratio of circle's circumference to its diameter.
![remote image](https://www.probability.ca/jeff/writing/pi1.jpg)

![local image](images/pi.png) *)
let pi = 3.14159

then just fsdocs build, no special options needed.

[tymokvo]

Does this work for .fs files in a project? The docs seem to indicate that this only works for literate scripts. I tried this in a .fs file and it seems to have no effect.

[nhirschey]

No, docs files must be .fsx, .md, or .ipynb.

[nojaf]

Did you try using relative paths for your Markdown image? That might work in xml doc comment.

[nhirschey]

Did you try using relative paths for your Markdown image? That might work in xml doc comment.

Yeah, good point that may be possible. For this use I think you’d probably need to turn on “use markdown comments”. See https://fsprojects.github.io/FSharp.Formatting/apidocs.html#Markdown-Comments

[tymokvo]

Hm, ok. Thanks for the tips, I will try those.

[tymokvo]

So the <img/> tag is preserved when using an XML comment. But, the image content is not copied into the output directory and the path is not resolved. It is just copied verbatim out of the documentation string.

The image also ends up in the index page for the namespace, which is probably not desirable in most cases.