I would like to embed (link to) images in generated documentation for a custom module API.

Perhaps there is already a way of doing this, if so please consider this a support request and please refer me to the method. Otherwise, I would like to suggest it as a feature.

I am developing a special object-oriented "bridge" tutorial module for Drupal7 that is coded to offer a high level of support for reverse-engineering of PHP to UML using PEAR PHP UML and has extensive graphical Unified Modeling Language (UML) diagrams for most major classes and interfaces of the tutorial module.

I would like to be able to display UML diagram images especially in the header docs for Classes and Interfaces, and in some cases also for operations/methods. And I would also like to be able to display Package overview diagrams for Namespaces.

An example of such a UML diagram for a Class is visible at DefaultMenuItem:

http://drupal7demo.webel.com.au/system/files/DefaultMenuItem.imp_.jpg

I would like to include such a diagram (by say 'src' reference) in the generated API docs for the Class at class DefaultMenuItem.

But when I naively insert the following into the header docs for the class:

<img src="http://drupal7demo.webel.com.au/system/files/DefaultMenuItem.imp_.jpg"/>

All I see in the generated API page is exactly the same thing but with the URL to the img as a link, like this:

<img src="http://drupal7demo.webel.com.au/system/files/DefaultMenuItem.imp_.jpg"/>

Grateful for any suggestions on how this can be done. See also:

http://drupal7demo.webel.com.au/module/ooe
http://drupal7demo.webel.com.au/module/ooe/uml
http://drupal7demo.webel.com.au/api/ooe

Comments

webel’s picture

PS: Neither 'image' nor 'img' appear anywhere at the community docs: API documentation and comment standards

webel’s picture

Issue summary: View changes
jhodgdon’s picture

Indeed, that sounds like a useful feature. You are correct that there is not currently any tag for inserting images. It would probably not be difficult to add, however.

Maybe it would be even more useful to have a generic tag like
@html ... @endhtml
which would allow you to put arbitrary HTML between those tags?

webel’s picture

Maybe it would be even more useful to have a generic tag like
@html ... @endhtml
which would allow you to put arbitrary HTML between those tags?

@ jhodgdon Sounds like an excellent idea, addresses my image case and opens up lots of other possibilities.

jhodgdon’s picture

We should also check Doxygen, PHPDoc, and other documentation standards and see what they do for this, before deciding. It is always better to use standards rather than inventing our own tags.

clemens.tolboom’s picture

@webel in #2168705: Add UML class Diagrams to api.drupal.org we have a similar request with a different approach.

Your diagrams are very interesting. Are those all generated by PEAR PHP UML or hand edited?

We use https://github.com/clemens-tolboom/uml-generator-php together with https://github.com/nikic/PHP-Parser ... can we team up to make api.d.o better?

drumm’s picture

API module will need to treat any arbitrary HTML from documentation as untrusted. At the very least, run filter_xss() on it.

Images on 3rd party sites have a habit of disappearing eventually, despite everyone's best intentions. If the images are documentation, maybe they should be checked in next to the code comments? Potentially doing that is another thing to check against Doxygen, PHPDoc, and other documentation tools. (If we go that route, API module should treat the image files as untrusted too; verify the files are actually images before copying to the files directory, and use https://drupal.org/project/filter_html_image_secure or equivalent on HTML)

webel’s picture

@clemens.tolboom remarked and asked:

Your diagrams are very interesting. Are those all generated by PEAR PHP UML or hand edited?

We use https://github.com/clemens-tolboom/uml-generator-php together with https://github.com/nikic/PHP-Parser ... can we team up to make api.d.o better?

A response to these broader questions has been moved off-site to Discussion: PHP UML (PEAR) and Drupal.

jhodgdon’s picture

So... Please take the discussion about UML diagrams elsewhere.... This issue is about being able to embed images in sites generated by the API module.

Because of the HTML filtering problems, and problems with external images, I do not think we really want this for api.drupal.org (as pointed out by drumm in an earlier comment).

So I think the best way to handle this is probably to add a hook to the API module that would let outside modules parse/filter the text after the API module is done with it. This way, you could define your own @tag, and do with it whatever you want for your own API site.

Specifically, in parser.inc, there is a function called api_format_documentation, which handles things like @link tags and other stuff encountered in documentation blocks.

This could do something just before the "auto_p" section, like:

  drupal_alter('api_formatted_documentation', $documentation);
 

If we did this, would that work for you?

jhodgdon’s picture

By the way... Comment #9 would be applicable if you wanted to put @img or @html or some other tag directly into your class's documentation header.

If you instead wanted to do something like "When I'm showing a class page, see if I have a class diagram and embed it" at display time, we would need a different hook.

That would be something like... let's see. Well, I don't think we need a new hook for that. For instance, when a Class page is created, that is in api.pages.inc in function api_page_class().

That function assembles all the information, and then calls:

  $output = theme('api_class_page', array('branch' => $branch, 'object' => $class, 'documentation' => $documentation, 'implements' => $implements, 'hierarchy' => $hierarchy, 'objects' => $objects, 'code' => $code, 'related_topics' => $related_topics, 'see' => $see, 'deprecated' => $deprecated, 'call_links' => $links));

So you could:
a) In a theme, override the api-class-page.tpl.php template
b) In a module or theme, add a preprocess function for this theme hook, and add information to whichever section you want it in.

Similarly, you could do things like this for the other page types, if you wanted to. They all have the 'object' variable there, so you can see what API documentation object is being output.

webel’s picture

@jhodgdon wrote:

Please take the discussion about UML diagrams elsewhere....

For now there is some discussion at Add UML class Diagrams to api.drupal.org. It combines some discussion of how to handle images at all, and some discussion of UML-specific diagramming issues. A response to broader questions from clemens.tolboom has for now been moved off-site to Discussion: PHP UML (PEAR) and Drupal.

jhodgdon’s picture

Status: Active » Postponed

I'm marking features as Postponed if I don't plan to work on them any time soon.