search

linkml / schemasheets

Structure your data in a FAIR way using google sheets or TSVs. These are then converted to LinkML, and from there other formats
https://linkml.io/schemasheets/
41 stars 5 forks source link

Feature Requests for GA4GH-VA shcema Web Docs #40

Closed mbrush closed 2 years ago

mbrush commented 2 years ago

Summarizing requests related to Web documentation content and format in this ticket. Providing as one long list for now, but happy to break out into tickets for specific feature requests as needed. @sujaypatil96 @sierra-moxon hope we can coordinate soon on these!

Content/Sections I’d like to see in each Class page (in the following order):

  1. Definition: a. already provided, and looks fine b. content comes from the s/s "description" field.

  2. UML-style diagram: a. already provided using YUML, but I find these YUML diagrams hard to read and not all that useful. b. It sounds like a new framework will be used to generate diagrams in the near future, so I will hold off on and requests here until I see how the new diagrams look.

  3. Parents: a. already present as a section on the page, and looks fine

  4. Description:
    a. A new section with the title "Description". b. This should contain content in the 'comments' field of the s/s. Ideally as a bulleted list of sentences rather than one long paragraph/block of text, for improved readability. c. At present text form the 'comments' column is in a table at the end of each Class page - but I’d like it front and center directly under the Definition.

  5. Implementation and Use: a. A new section with the title "Implementation and Use" b. content would ideally be derived from the s/s - but not sure how to do this in practice? . . . I hear that the Annotations feature might let me just create a new 'Implementation and Use' column and give it whatever name I want. Not sure what tooling would be needed to generate a proper section in the Class web page that holds the content. d. I'd also want this presented as a bulleted list of sentences/short paragraphs, rather than one long blob of text.

  6. Own Attributes: a. This section already exists in each Class page b. content of course comes from the s/s c. prefer 'expanded' form - not tables - as this better accommodates the types and amount of text I want to provide in describing each attribute. (see below) d. don't think we need the class -> attribute pattern for 'own' attributes (no need class context when you are already on the class page and the section says 'own' )

  7. Inherited Attributes a. This section already exists in each Class page b. content generated from s/s but pulling in all attributes from parents of a given class

  8. Data Examples: a. A new section called "Data Examples" b. content would be nicely formatted yaml or json data examples - e.g. like those in the VRS RTD docs here), Ideally with some lead in text that describes what is being represented (but this could be part of the data example text block, as a # comment preceding the data itself) c. Chris suggested a housing these in a 'Data Examples' directory in the repo - and pulling relevant examples in to a Class web page from these example files automatically. These data examples could then serve multiple purposes (documentation, texting/validation, etc.)

Content/Fields I’d like to see in for each Attribute of a class, as shown in a Class page

  1. The attribute name, description, cardinality, and range are already provided and look good as is.
  2. I’d also like to include a 'Comments:' field that holds text from the ‘comments’ column in the s/s - to provide additional clarification on meaning and usage of an attribute.
sujaypatil96 commented 2 years ago

This issue can be moved to https://github.com/sujaypatil96/ga4gh-va since it doesn't require any tweaks in schemasheets. Modifying the templates for gen-doc, or gen-markdown will help customize the pages we are currently seeing in the web docs.

mbrush commented 2 years ago

OK - closing this ticket, and copied into your repo Sujay. Thanks!