Hi Janardhan,
Reworking the documentation seems like a really good idea! A first step in my opinion is to start in the main repository. I would suggest the following: - Merge the current gh-pages branch into master docs folder. - Change the documentations page : http://apache.github.io/systemml/ to use the docs folder for documentation. Should be doable inside the settings on the repository. - Delete the gh-pages branch I want this change because then new PRs can change the documentation in one PR rather than two (which to be honest is not going to happen most of the time). The downside (we have to mention this) is that when you clone the repository, you have slightly larger downloads, but i think the trade-off is fair. If you see any other issues please mention these in this thread. Next task I would like to suggest to include: - Java docs generated and - Python docs generated to also be included as a sub-folder in docs, so that the current webpage contains the docs for that to. How to include these in a sensible manner is currently a good question, and has to be seriously well considered. Including these will also enable us to move documentation closer to the individual code parts, making it again more likely to get the documentation done. Another more programmatic task is to make a parser for our DML files, such that we can generate webpage documentation based on the documentation syntax used (much like the python and java docs generator). This would be great since it will remove the duplication of documentation in the individual DML files, and the documentation we have already in files such as: docs/dml-language-reference.md. This also gives us an excuse to clean up that documentation/scripts which has very different implementations in our scripts folder: examples: - <https://github.com/apache/systemml/tree/master/scripts> https://github.com/apache/systemml/blob/master/scripts/nn/layers/batch_norm1d.dml<https://github.com/Baunsgaard/systemml/blob/master/scripts/nn/layers/batch_norm2d.dml> - <https://github.com/Baunsgaard/systemml/blob/master/scripts/builtin/glm.dml> <https://github.com/apache/systemml/tree/master/scripts> https://github.com/apache/systemml/blob/master/scripts/algorithms/Cox.dml Furthermore, I would suggest to postpone changing the main website: https://github.com/apache/systemml-website But that task has to be started when the next release is scheduled, because then we need to find out how to copy the current documentation to a archive list of static webpages located: https://systemml.apache.org/documentation best regards Sebastian ________________________________ From: Janardhan <janard...@apache.org> Sent: Sunday, May 24, 2020 11:02:53 AM To: dev@systemml.apache.org Subject: [DISCUSSION] Website stack `systemml.apache.org`. Thanks. Hi Sebastian, In our discussion[1][2] a while ago, there was a topic about changing website stack. Let us start a discussion about this in this thread. We are planning to work on this, after a feasibility study and tech stack vetting. Anybody would like to give suggestions would be great. [1] https://github.com/apache/systemml/pull/877 [2] https://github.com/apache/systemml-website/pull/66 Thank you, Janardhan
