Docgenerator naming

[mscuthbert]

Wondering if I can get a +1/0/-1 on this -- not asking this to be done yet.

I've found the naming in the docgenerator files (at least for musicxml) confusing in a couple of places, and I'm worried that it might throw potential contributors for a look if they haven't been programming/working with python or Django for it bit.

Is there a way that the outer and inner directories of the docgenerator can be called different names. Like call the outer one "makeDocumentation" (or make_docs) and leave the inner one as "docgenerator" -- or leave the outer one "docgenerator" and make the inner one "generator_code" or something (the second solution is less desirable and harder to migrate in Django, but wanted to give it as an option).

I didn't quite make it to 20 years of teaching music computation at MIT, but in the 17 years I did it, I realized that nothing was more confusing to the younger generation, who no matter how good they are at CS and programming have the weakest of understanding of folders, than having an outer folder and an inner folder with the same name.

If anything will make Python unappealing to the next generations, it's this default packing structure in pip. (I tried for years to make it so that the outer-meta/testing/docs folder for music21 was called music21base and the "src" folder was called music21 but I eventually needed to give in to the standard python/python/ standard of folder redundancy.)

---

The other requested rename for clarity is the spec folder -- which looks to me as if it should hold the musicxml or mnx specs. It looked to me that this is the folder which would be read from in order to create the /schema/ or /specification/ and /docs/ folders. But instead, this is the name of the Django app that helps to manage the spec. Can we rename it specmanager? or something that makes it clear that it is part of spectools etc., but not the folder holding the spec itself?

If there is agreement on either or both of these ideas, I'll work on the code changes needed to make this happen. Asking for guidance not charity.

Thanks!

[samuelbradshaw]

Interesting – having not been a teacher or professor of younger generations, I learned a few new things reading that article! I'm not opposed to changes that might make things more intuitive, but I haven't been involved in any of the Django or documentation work.

[adrianholovaty]

Thanks for the suggestions. In 726f071462 I've renamed the inner spec module to spectools — that should help prevent people from thinking that directory contains the actual spec.

Note: as a consequence of that change, anybody with a local DB of the MNX spec will need to delete the local SQLite file and regenerate it.

In 7c7d0ca6f1 I renamed the top-level docgenerator directory to doctools. It's kind of silly having two separate names now, but at least we can avoid having the duplication.