search

INCATools / ontology-development-kit

Bootstrap an OBO Library ontology
http://incatools.github.io/ontology-development-kit/
BSD 3-Clause "New" or "Revised" License
219 stars 54 forks source link

Add a human readable reference guide explaining the project YAML parameters #864

Closed StroemPhi closed 1 year ago

StroemPhi commented 1 year ago

Spun out of a Slack discussion, we've identified the need to have a more practical overview of what project.YAML parameters are available and how to set them, based on https://github.com/INCATools/ontology-development-kit/blob/master/docs/project-schema.md.

StroemPhi commented 1 year ago

Is related to #866

pfabry commented 1 year ago

As a first step, maybe we could make project-schema.md more visible for ODK users? Personally, I wasn't aware of this file's content before the Slack discussion. This file (and all the markdown files in ontology-development-kit/docs in fact) should be generated iin /docs when you generate a new repo.

StroemPhi commented 1 year ago

I agree that having project-schema.md in the docs folder that gets generated by ODK would be really helpful. The other MDs however are mostly redirects to the OBOOK. So wouldn't it thus be better to only add one or more links to the OBOOK in the default doc templates of ODK?

StroemPhi commented 1 year ago

Regarding the suggested first step of exposing the project-schema.md to ODK users, I would suggest to link to it under the Where to get help section of the ODK README.

Regarding the integration into the autogenerated docs of an ODK based repo, I would add a link to the project-schema.md in a appropriate section of https://github.com/INCATools/ontology-development-kit/blob/master/template/_dynamic_files.jinja2.

Regarding fleshing out the documentation of the schema itself, I would then suggest to iterativly improve the project-schema.md, as it then serves as single point of truth. Although I wonder if it would be better to have such a more fleshed out MD live in the OBOOK instead of the ODK repo?

Any thought @matentzn or @gouttegd?

matentzn commented 1 year ago

Sure, if you can make a PR with a proposal, that would be great!

StroemPhi commented 1 year ago

point 1 & 2 from https://github.com/INCATools/ontology-development-kit/issues/864#issuecomment-1562437067 are addressed in the linked PR. Regarding Point 3, before fleshing it out, I need to know, if the project-schema.md is autogenerated. Woulnd't make much sense to edit it if so.

StroemPhi commented 1 year ago

I specified that #879 would close this issue, as I think it would be better to open a new issue for the actual fleshing out of the schema description/documention.