openstate/openonderwijsdata-api — pull request #12 by bennokr (2014-10-17 16:09:25+00:00)
Title: Combining validation and documentation

I made a way to add descriptions of the fields to the validation schemas. Then we can use those descriptions to automatically generate the API documentation.

By explaining what the fields mean exactly where we specify what their values should look like, we have a much more structured way to describe the data in the API. Every schema definition file starts with the module docstring that you can use to describe the data source. Each schema class has its own docstring too, which you can use to describe the dataset. Finally, you can run [`generate_docs.py`](https://github.com/openstate/openonderwijsdata-api/blob/e2eb47b27368a5fea94b638fdee953b4b6798454/onderwijsscrapers/onderwijsscrapers/generate_docs.py) to combine all documentation into one file. The data header and footer for the API data docs are in that file as well. It calls the [`generate_documentation(schema)`](https://github.com/openstate/openonderwijsdata-api/commit/e2eb47b27368a5fea94b638fdee953b4b6798454#diff-2cdf135510c76c5df3fdffaaea0f5153R47) function for every schema that we want in the documentation, combines all the material, and outputs a ReStructuredText source file. This way, we could add the documentation generation to the sphinx build script later.

However, not all the data is documented and validated yet. But now we know that if a dataset is in the documentation, it is also validated and vice versa.