Bug 1014859

Summary: [RFE] improve context-sensitive help csv mapping files
Product: [Retired] oVirt Reporter: Greg Sheremeta <gshereme>
Component: ovirt-engine-coreAssignee: Greg Sheremeta <gshereme>
Status: CLOSED CURRENTRELEASE QA Contact: bugs <bugs>
Severity: low Docs Contact:
Priority: unspecified    
Version: unspecifiedCC: acathrow, alonbl, ecohen, iheim, yeylon
Target Milestone: ---Keywords: FutureFeature
Target Release: 3.4.0   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard: ux
Fixed In Version: ovirt-3.4.0-beta3 Doc Type: Enhancement
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2014-03-31 15:04:41 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:

Description Greg Sheremeta 2013-10-02 23:41:49 UTC 
Description of problem:
oVirt can support context-sensitive help for dialogs by filling out the following documentation mapping files:
UserPortalDocumentationPath.csv for user portal
DocumentationPath.csv for webadmin

As of now, these files are empty, and their syntax is a mystery.

1. Add a README.manual file that describes the format of these files.
2. Add support for #comment style comments within the file
3. Determine if the fields in the file can be trimmed down
4. Make sure the file contains all of the possible help locations in oVirt, even if we have no documentation for those locations. (Currently we have none, but if we put all the dialog names in the file, it acts as a template allowing for people to very easily add documentation.)
5. Determine if the csv files can be generated at build time, or if they can be replaced with annotations.

Version-Release number of selected component (if applicable):
n/a

How reproducible:
n/a

Steps to Reproduce:
n/a

Actual results:
n/a

Expected results:
n/a

Additional info:
n/a
Comment 1 Alon Bar-Lev 2013-10-03 11:25:40 UTC 
We discussed another alternative... keep empty file, but be able to generate a template out of code annotations, so by adding a new help location, nothing should be updated manually.
Comment 2 Greg Sheremeta 2013-10-03 11:26:53 UTC 
Yes, I have that as #5 in the list above.
Comment 3 Alon Bar-Lev 2013-10-03 11:29:36 UTC 
(In reply to Greg Sheremeta from comment #2)
> Yes, I have that as #5 in the list above.

yes... it should be #1, so we avoid most of the work if that succeeds.
Comment 4 Greg Sheremeta 2013-10-03 11:48:36 UTC 
(In reply to Alon Bar-Lev from comment #3)
> 
> yes... it should be #1, so we avoid most of the work if that succeeds.

Fair enough.
Comment 5 Greg Sheremeta 2013-11-07 20:59:03 UTC 
Updates this enhancement like so.

Description of problem:
oVirt can support context-sensitive help for dialogs by filling out the following documentation mapping files:
UserPortalDocumentationPath.csv for user portal
DocumentationPath.csv for webadmin

As of now, these files are empty, and their syntax is a mystery.

1. Add doc tags and comments to code -- submit ovirt-engine patch that adds setHelpTag calls such as 
setHelpTag("add_new_vm", "VMs Tab > Add New VM");

This allows someone to grep the code like so:
grep -r setHelpTag <path>
and get a quick list of all the help locations.

2. Change frontend to consumes JSON files containing doc mappings, no more CSV.
A. JSON file locations
one master index at engine, index.json
frontend first accesses the /ovirt-engine/doc/manual/index.json, then extract the key using the application name
key shared with branding, and load all files, last wins.
B. multiple files per application

index.json
---
{
    "webadmin": ["helptags.common.json", "helptags.webadmin.json"]
    "userportal": ["helptags.common.json", "helptags.userportal.json"]
}
these also live at /ovirt-engine/doc/manual/

helptags.*.json
---
{
    "add_new_vm": "/help/Adding_A_New_VM.html",
    <etc.>
}

So, now someone can 
grep -r setHelpTag <path>
and easily keep these JSON files up to date.

3. Sharing of application id between branding and doc
Get the branding application id as an index to the index.json
Comment 6 Sandro Bonazzola 2014-02-19 12:26:50 UTC 
This bug is referenced in ovirt-engine-3.4.0-beta3 logs. Moving to ON_QA
Comment 7 Sandro Bonazzola 2014-03-31 15:04:41 UTC 
This is an automated message: moving to Closed CURRENT_RELEASE since oVirt 3.4.0 has been released.