search

sul-dlss / cocina-models

Cocina repository data model (implemented in Ruby)
https://sul-dlss.github.io/cocina-models/
3 stars 0 forks source link

Generate user documentation from description validation files #385

Closed arcadiafalcone closed 2 years ago

arcadiafalcone commented 2 years ago

In order to prevent having to maintain documentation of evolving validation standards in multiple places, it would be useful to be able to automatically generate user-readable documentation directly from the YAML configuration file for type validation.

Some notes on the conversion:

  1. The section header in the YAML file is converted to separate words + "types", so contributor.name becomes "Contributor name types"
  2. If the section header ends with structuredValue, "part types for structured value" is added in the markdown, so contributor.name.structuredValue becomes "Contributor name part types for structuredValue"
  3. If the section header ends with groupedValue, "types for grouped value (MODS legacy)" is added in the markdown, so contributor.name.groupedValue becomes "Contributor name types for grouped value (MODS legacy)"
arcadiafalcone commented 2 years ago

Sample Markdown file with selections from description_types.yml documentation_test.md

Equivalent YAML file available in shared drive: https://drive.google.com/drive/u/0/folders/1H4K8cV5ntqdgT45hcWIyYWeliTHCdvQ6

mjgiarlo commented 2 years ago

have an in-progress PR up: https://github.com/sul-dlss/cocina-models/pull/396 with thoughts on how we might proceed

Unassigning on my way out for the week 👋🏻

justinlittman commented 2 years ago

@arcadiafalcone @andrewjbtw Here it is: https://sul-dlss.github.io/cocina-models/description_types.html