This is awesome! I am really glad this is being done
I personally don’t have a clear idea of the border between the Push language and the Push language implementation (clojush, pysh, klapaucius, etc) when it comes to the instructions/atom generators. Does anyone else?
If the documentation you are creating is going to be about Push in general then I agree that the Push Redux makes the most sense. However this is tricky because if you start to write documentation on each individual instruction, or how certain atom generators work, suddenly there are major differences between implementations.
Clojush and Pysh contain the mostly the same instructions, but some have different names. Klapaucius is a whole different world. Also, other types of atom generators are different between implementations, as shown by our recent topic on output values.
That isn’t to say to say there isn’t really helpful documentation to be written that isn’t specific to a single implementation. I just predict it will be harder to write.
In my opinion, some lower hanging fruit that would still be extremely helpful would be to improve the documentation of one implementation. I assume you would want to start with Clojush, but this will probably need to be done in some form for all implementations. If this is more along the lines of what you were thinking, then I have some suggestions:
I would strongly consider capturing this documentation in the Clojush repository somehow. If contributors can’t push their own updates to the documentation along with their code, the documentation will probably be out of date within a month.
The closer the documentation of each instruction can be to the code implementing that instruction, the better. That way documentation can be read within the source code, and it is much easier to stay in sync. Unfortunately, I don’t think you can adequately use docstrings because when the instruction set is being built (in pyshgp and Clojush) there are functions that are used to create the same instruction multiple times but for different stacks (ie.
string_pop are all generated by this one function). You would have to come up with a way to generate informative docstrings for each instruction created by the function, which seems difficult to me.
I realize that I am probably making this far more complicated than anyone wants . Perhaps it is adequate to simply have 1 page per implementation on the redux that documents the instruction set supported by that implementation.