[MISC] move schema documentation into the schema directory

[Remi-Gau]

fixes #716

• add a README in the schema folder
• move some of the schema related content to that README and only keep in contributing.md info about how to modify the schema

[Remi-Gau]

FYI: the schema macro complains about the README when building the doc. I suspect this is expected given the python code expects only .yml but this may confuse people in the future.

[tsalo]

FYI: the schema macro complains about the README when building the doc. I suspect this is expected given the python code expects only .yml but this may confuse people in the future.

I've gotten similar complaints about .DS_Store files on my Mac. Perhaps we should have load_schema() just ignore other file types, instead of raising warnings about them.

[Remi-Gau]

I've gotten similar complaints about .DS_Store files on my Mac. Perhaps we should have load_schema() just ignore other file types, instead of raising warnings about them.

Good idea.

[tsalo]

Not just the entity table, but also the entity definitions appendix and filename patterns throughout the specification.

[marcelzwiers]

I was trying to see if I can do a pull request about this suggestion I made for renaming the entity field (to key) in the entity.yaml file. But I have a hard time to find all the places that would be affected by this change, can you perhaps tell me, how do I test this?

[Remi-Gau]

I suspect most of the changes to be done there will be in the tools/schema_code, right @tsalo ?

Should we add a README into the tools folder with at least some very brief explanation of what to find in there?

[tsalo]

I agree that the code in that tools folder is where you will get the best idea of what parts of the schema are actively in use. It would be useful to add a README to that folder for right now, but I think we'll be moving that code into its own repository in the long run.

An alternative would be to focus on documenting the functions that are directly used in the specification (i.e., macros.py).

[Remi-Gau]

OK I can try checking the code base and improving the doc strings.

[sappelhoff]

fyi @Remi-Gau, I applied Taylor's comments and rebased this on master so if you want to continue on this locally, you may want to run git fetch and git reset --hard origin/remi-schema-doc (provided that you don't have non-committed local changes)

[tsalo]

I'm quite happy with this, and would like to build off of it in #762. Hopefully we can merge soon.

[sappelhoff]

If Taylor is happy with this, so am I, from my side, we can merge.