Hi Sebastian, Can we move the `docs` folder in the existing `master` branch and merge the `gh-pages` branch to `docs` folder in the top-level directory. :)
- Janardhan On Sun, May 24, 2020 at 3:28 PM Baunsgaard, Sebastian <baunsga...@tugraz.at> wrote: > 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 >
