Provide better documentation of config options

[dosumis]

It is currently hard to work out what config options do except by looking at examples. I was hoping that schema would be usable for this, but descriptions are largely empty and it seems from the README this is just autogenerated from odk.py.

Could we have a complete schema with descriptions? There are some easy ways to convert JSON schema to browsable html.

Motivating use-case: setting up a repo with Robot templates & related build infrastructure. Can I use robotemplate_group for that?

[matentzn]

Yeah, sounds reasonable! I added this ticket to our meeting agenda as well. Providing better documentation has been an open ticket here for 3 years :D I think we should be able to generate a schema, but you can also look at the file called "project.yaml" when you generate any project (in the target dir, for example: target/pato/project.yaml). This seems to have most if not all options:

allow_equivalents: all
catalog_file: catalog-v001.xml
components:
  directory: components
  filename: null
  products:
  - filename: pato_ext.owl
    source: null
  source: null
contact: null
contributors: null
creators: null
description: None
dosdp_tools_options: --obo-prefixes=true
edit_format: obo
exclude_tautologies: structural
export_formats:
- owl
- obo
- json
git_user: ''
github_org: pato-ontology
gzip_main: false
id: pato
import_group:
  directory: imports/
  disabled: false
  ids: null
  products:
  - description: null
    id: ro
    mirror_from: null
    rebuild_if_source_changes: true
    robot_settings: null
  - description: null
    id: chebi
    mirror_from: http://purl.obolibrary.org/obo/chebi.owl.gz
    rebuild_if_source_changes: true
    robot_settings: null
  - description: null
    id: go
    mirror_from: null
    rebuild_if_source_changes: true
    robot_settings: null
  - description: null
    id: pco
    mirror_from: null
    rebuild_if_source_changes: true
    robot_settings: null
  - description: null
    id: uberon
    mirror_from: null
    rebuild_if_source_changes: true
    robot_settings: null
  rebuild_if_source_changes: true
import_pattern_ontology: false
license: https://creativecommons.org/licenses/unspecified
namespaces: null
obo_format_options: ''
pattern_group: null
pattern_pipelines_group: null
primary_release: full
public_release: none
public_release_assets: null
reasoner: ELK
release_artefacts:
- base
- simple
- full
release_date: false
repo: pato
report_fail_on: none
robot_java_args: -Xmx8G
robot_settings: null
robot_version: null
robotemplate_group: null
subset_group: null
title: Phenotype And Trait Ontology
travis_emails: null
uribase: http://purl.obolibrary.org/obo
use_dosdps: false
use_external_date: false

[matentzn]

Check also this unsatisfying answer: https://github.com/INCATools/ontology-development-kit/issues/469#issuecomment-918550680

[matentzn]

@hkir-dev would you be able to take this on?

Not urgent, but getting very important given how complex ODK config has become:

https://github.com/INCATools/ontology-development-kit/blob/master/schema/project-schema.json

[hkir-dev]

Sure, I can take this

[matentzn]

Awesome. I see something that turns that yaml into a nice markdown page..

[matentzn]

Dont forget to link from all relevant OBOOK pages.

[hkir-dev]

completed: https://github.com/INCATools/ontology-development-kit/blob/master/docs/project-schema.md