search

irllabs / ml-lib

A machine learning library for Max and Pure Data
Other
274 stars 40 forks source link

Inconsistent Documentation / Help files #141

Closed graphographer closed 6 years ago

graphographer commented 6 years ago

The help patches mentioned in https://github.com/cmuartfab/ml-lib/issues/139 are in most cases inconsistent with the documentation in http://cmuartfab.github.io/ml-lib/#class-reference-mldtw. The latter reference seems to be mainly correct, whereas the messages provided in the former help patches will generate "not supported" errors.

For example, "save" and "load" are incorrect, whereas "write" and "read" are correct.

jamiebullock commented 6 years ago

Thanks for the report. As you say it is the help files here that are incorrect. Soon the help files will be auto generated from the same source as the html docs so such inconsistencies will be impossible!

For now, can I persuade you to send a corrected version of the help and I’ll add it to the repository.

jarmitage commented 6 years ago

Hi @jamiebullock, are you still planning to auto-generate help files? What's the workflow for making that happen?

I ported the .maxhelp for dtw to Pd here (workflow needs correcting). Would this help you generate the rest of the files?

jamiebullock commented 6 years ago

Yes I am, and this should happen "fairly soon".

I'm going to use the same doc source used for http://cmuartfab.github.io/ml-lib and insert the documentation into Max and Pd templates. The help files will then get "built from a command line tool for each release

Thanks for the porting. I will look at it and potentially use it in the templating.

jarmitage commented 6 years ago

That's great, looking forward to it!

I'd be interested to see how the command line tool works as well if possible

jamiebullock commented 6 years ago

Well... this is pushing the limits of "fairly soon", but there is now a set of auto-generated Pd help files in the documentation download for the latest release here. The patches are in help/pd and contain exactly the same information as the HTML docs so should be completely consistent.

The formatting could still be improved, but hopefully this is a massive improvement only having a couple of help files that are factually wrong!

In the next release I'll look at getting these into the main downloads rather than a separate documentation zip.

jarmitage commented 6 years ago

Super cool, thanks @jamiebullock!