systemml-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From arnab phani <phaniar...@gmail.com>
Subject Re: [DISCUSSION] Website stack `systemml.apache.org`. Thanks.
Date Sun, 31 May 2020 13:15:44 GMT
Hi,

Another advantage of markdown syntax is that it gives more freedom to add a
description as needed. Java methods and builtins might not fall in the same
bucket and different builtins might need different ways to describe it.
For example, glm needs more details than other built-ins. Too much
standardization can be a bad idea.

Regards,
Arnab.

On Sun, May 31, 2020 at 9:55 AM Baunsgaard, Sebastian <baunsgaard@tugraz.at>
wrote:

> Hi Janardhan,
>
>
> That would be one option, lets call it option 1, I have another suggestion:
>
>
>   1.  Markdown syntax with out commented individual lines.
>   2.  Jdoc like syntax with annotations
>
> Pros and cons
>
>   *   1 Pros
>      *   Easy Syntax most ppl know it.
>      *   Easy to  implement.
>   *   1 Cons
>      *   Enables custom docs (everyone make their own distinct format
> again)
>      *   No standard way of verifying correctness of the docs (correct
> parameter names etc.)
>      *   No standard way of marking Input, return parameters.
>      *   Requires modified Syntax with # at each line. where # normally
> means header in markdown
>   *   2 Pros
>      *   Easy Syntax Java ppl know it
>      *   Standard way of making input
>      *   Do not have to change any syntax at all from Jdoc
>      *   Already supported syntax in DML
>   *   2 Cons
>      *   Harder to implement since one would have to look into java doc
> extraction and what is needed to support that, maybe we have to make such a
> thing ourselves?
>
> I personally like option 2 with Jdoc more and then extending into
> automatically parsing and making the either markdown files or HTML files
> for the docs that you either way have to do in option 1.
>
> Best regards
> Sebastian
> ________________________________
> From: Janardhan <janardhan.pulivarthi@gmail.com>
> Sent: Sunday, May 31, 2020 9:25:43 AM
> To: dev@systemml.apache.org
> Subject: Re: [DISCUSSION] Website stack `systemml.apache.org`. Thanks.
>
> Hi Sebastian, :)
>
> Since the builtin DML files do not have full documentation yet, Can we
> write
> markdown syntax with the following heading in each dml file itself!
>
> 1. Function description
> 2. Usage
> 3. Arguments
> 4. Returns
> 5. Usage
>
> After that, as you've mentioned can be parsed with only removing # at the
> start of each line, and write
> all this data to one `builtins-reference.md` file.
>
> Thank you,
> Janardhan
>
> On Tue, May 26, 2020 at 5:05 PM Baunsgaard, Sebastian <
> baunsgaard@tugraz.at>
> wrote:
>
> >
> > If this is meant as a question then, yes from me (this probably calls for
> > a vote?), if:
> >
> >
> >   1.  someone is able to change the settings for the repository, to use
> > the docs folder as the GitHub docs folder.
> >   2.  someone wants to make a PR containing the content of the gh-pages
> > branch.
> >
> > Best regards
> > Sebastian
> > ________________________________
> > From: Janardhan <janardhan.pulivarthi@gmail.com>
> > Sent: Tuesday, May 26, 2020 1:22:11 PM
> > To: dev@systemml.apache.org
> > Subject: Re: [DISCUSSION] Website stack `systemml.apache.org`. Thanks.
> >
> > 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 <
> > baunsgaard@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 <janardhan@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
> > >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message