Include link to documentation for an addon?

Projects Add-On Index
1

Is it possible to add the Module Documentation link in the AddOns next to the module information? It would help to users to get some information about the module at that same time :slight_smile:

image
image1631Ă—501 47.6 KB

Cc : @darius @reubenv

1 Like
2

@suthagar23 great idea! It’s very doable, with a bit of code. I don’t have time to implement this at the moment, but I’ll give my design thoughts here if someone else wants to pick it up. (I had been thinking about including a link to the module’s source code, so I’ll suggest a design that can handle both.)

We should let people specify an arbitrary list of “Links” when they define they addon in add-ons-to-index.json, which would look like this:

{
  "uid": "org.openmrs.module.addresshierarchy",
  "name": "Address Hierarchy",
  // ...
  "links": [
    { "rel": "documentation", "href": "https://wiki.openmrs.org/x/shIz", "title": "OpenMRS Wiki" },
    { "rel": "source", "href": "https://github.com/openmrs/openmrs-module-addresshierarchy" }
  ]
}

This would also require a change in the AddOnToIndex class, and in our elasticsearch mappings. (I don’t think there’s any value in making the links searchable, e.g. it’s not helpful that if a user types “github” in the searchbox they see all addons whose source code is in github. But I probably wouldn’t bother to do the extra work to exclude these fields from the full-text index either.)

Then the webapp should be updated to display each link on the Show.jsx page (I would add it between Hosted On and Maintainers, here.)

A few more thoughts:

  • I would special-case “documentation” and “source” and display rows for these all the time (even if empty), and I’d also add a nice label for them.
  • Links with other values of rel would be displayed verbatim. People could use this flexibly for other cases. (e.g. the ebolaexample module could include a link to the journal article we published about OpenMRS Ebola)
  • I would merge multiple links with the same “rel” value into one row in the webapp display (e.g. the Documentation row could show links for User Documentation and Admin Documentation)

Anyone interested in picking up this work? @reubenv or I could walk you through the dev steps.

2 Likes
3

@suthagar23 I found some time to implement this. (Really I just wanted to write some code and this seemed like a manageable chunk.)

Please check it out, and if you agree this is working, then mark AO-17 as closed.

For testing purposes I added links to the Address Hierarchy module and the Ebola Example module. I created AO-18 for adding links to all the other existing modules, but you can also follow the example there just to update your own modules/owas.

2 Likes
4

Looks great, thanks @darius ! Thanks, @suthagar23 for the initiative as well, this was a much-needed feature in my opinion. So sorry I missed this notification( had read it while in college but forgot about it when I was back home :sweat_smile: )

That being said, I’d like to urge all module devs/maintainers to update your respective modules(Especially for the ones included in official releases with distributions like Ref App etc. I’ll be adding some links to the popular modules but it would be a daunting task to add the links to all the modules at once and hence it would be great if everyone could ensure that their modules are updated)

1 Like
5

Thanks a lot @darius. I totally fine with the implementation and will close the AO-17 ticket as it’s completed by now.

PS : I’m sorry to say that, I couldn’t take it in my hand since I was busy with the GSoC final steps :smile:

6

Yes, Indeed since the only one who knows which documentation is needed as the first choice for the module is the actual developer. So updating the documentation with the AddOn would be great help to make it in live :slight_smile:

7

Further,

  1. Is there any ways to reduce the complexity while adding the information to the add-ons-to-index.json. Eg : Building a dashboard for creating & updating the information about the modules directly from the AddOns (can restrict by the OpenMRS authentications)

  2. PUBLISHING-AN-ADD-ON doesn’t reflect the whole fields(available) which can be added into the JSON configs (Eg : maintainers can add a URL for their name - but most of them missed to add that). The page only mentioned the required fields. It can be reflected by easily adding a sample JSON Config to this page.

Any comments for this too :slight_smile: