GSOC Elixir ExDoc project

[b...@pdx.edu]

Hello all,

I saw the listing for the ExDoc project, and I am interested in exploring the project and potentially applying to work on it.

A bit of introduction. I am working on my masters in Computer Science at Portland State University. My focus is on programming languages, and I currently work as a TA for our undergraduate programming languages courses.

The ExDoc project caught my attention because it offers a chance to work with Elm and to learn Elixir.

I have written a couple of applications in Elm. The larger project is a collaborative web audio application. Users make music together in a DAW-style interface, and their collaboration is coordinated by a server over websockets. The application is live at lunar.rocks. (Note that my collaborator is working on re-implenting the back-end, and some multi-user features may not work consistently. The application should work fine for a single user. If not, let me know and I am happy to restart the server.)

My other Elm application is a minimalist music application that also uses web audio. This application is a static site and can be viewed at brianginsburg.com/minima.

Until a couple of days ago, I had no experience with Elixir. In addition to Elm, I am familiar with Haskell and Scala, and I am excited to learn Elixir. That being said, if this lack of experience would hinder my helpful contribution, please let me know.

My plan for exploring the project include learning Elixir, getting familiar with code base, and looking for issues where I can contribute. Are there other steps that I can take to get involved?

Thank you
Brian Ginsburg
brianginsburg.com

[José Valim]

Hi Brian!

I don't think lack of Elixir knowledge will be a problem given you have plenty of experience with Elm and you are familiar with Scala and Haskell.

The main goal with this project is to improve the maintainability of the current codebase, so a strong test suite should be considered. We want to keep the existing functionality and hopefully make it easier to add new behaviour in the future.

There is also one important limitation: today pages are accessible offline and we have to keep it working - this means while functionality like faster page loads via AJAX would be welcome, the whole application still need to work without them.

Finally, exploring Elixir is a good plan! You probably will only need to change the ExDoc code in regards to template generation and that should be relatively straight-forward. Maybe a good project to get started with contributions is ExDoc itself but there isn't much work pending there.

José Valim

www.plataformatec.com.br

Founder and 

Director of R&D

[b...@pdx.edu]

Great, thank you for explaining the testing and offline considerations. I will keep these in mind while I am looking through the code base. More questions may be coming when I have a better understanding of how ExDoc works now.

I will keep an eye on the repository, and if an issue comes up that I can address, I will take it on.

Thanks!
Brian Ginsburg
brianginsburg.com

[b...@pdx.edu]

I have been looking into possible ways to approach this project.

For the application to work offline, I think it will need to generate static pages. This seems to be the way ExDoc currently works.

I reached out to the Elm community for ways to generate static pages from an Elm application. They recommended elm-static-html-lib (https://github.com/eeue56/elm-static-html-lib). This library treats Elm files as templates rendering them with JSON input.

This seems to be a departure from the templated markup currently in use. I think for this to work, the backend would need to produce JSON for elm-static-html-lib to consume. Another restriction is that this libary cannot properly render Markdown (https://github.com/eeue56/elm-static-html-lib/issues/7).

A dynamic version of the application would also benefit from JSON, requesting it as needed to render pages. The Elm code used for the dynamic application and for generating static pages would likely be similar.

I'm hesitant with this approach because it seems like more change to the backend than was intended. Are there are other suggestions on how I could approach this?

Brian Ginsburg
brianginsburg.com

On Sunday, February 18, 2018 at 12:39:03 AM UTC-8, José Valim wrote:

[José Valim]

Brian, couldn't we continue to generate the pages statically with HTML as we go today and use a script tag to bring the Elm code in?

José Valim

www.plataformatec.com.br

Founder and 

Director of R&D

[b...@pdx.edu]

We can bring the Elm code in this way, but I don't think that Elm can directly read the existing markup to interact with it as JavaScript does.

Elm usually generates and manipulates its own markup, and many of the benefits of Elm rely on this as part of the Elm Architecture (https://github.com/evancz/elm-architecture-tutorial/). It can be added to an existing application in pockets, and communicate with the application through JavaScript (https://guide.elm-lang.org/interop/javascript.html).

There may be a way to directly replace the JavaScript without changing the markup, but I am not seeing a sensible way to do it.

It may be possible to convert parts of ExDoc to Elm without disrupting everything. This approach would still rely on JavaScript to communicate between Elm and the rest of the application, but it's not a bad approach to experiment with Elm a bit to see how it would work.

Brian Ginsburg
brianginsburg.com

[Milton Mazzarri]

On Feb 23, 2018 10:50, <b...@pdx.edu> wrote:

I reached out to the Elm community for ways to generate static pages from an Elm application. They recommended elm-static-html-lib (https://github.com/eeue56/elm-static-html-lib). This library treats Elm files as templates rendering them with JSON input.

This seems to be a departure from the templated markup currently in use. I think for this to work, the backend would need to produce JSON for elm-static-html-lib to consume. Another restriction is that this libary cannot properly render Markdown (https://github.com/eeue56/elm-static-html-lib/issues/7).

A dynamic version of the application would also benefit from JSON, requesting it as needed to render pages. The Elm code used for the dynamic application and for generating static pages would likely be similar.

I'm hesitant with this approach because it seems like more change to the backend than was intended. Are there are other suggestions on how I could approach this?

Brian, you certainly need to check the pros and cons of this approach. To have some data at hand and if you have some time, what you can do is a proof of concept, you can create a new project that depends on ExDoc and add a JSON formatter that suit the needs of your frontend, as a reference you can take this PR:

https://github.com/elixir-lang/ex_doc/pull/720/files

If your Elm library cannot render Markdown properly, you should check if make sense at all to include the HTML produced by Earmark (or another Markdown parser supported by ExDoc) as part of your JSON.

Hope this helps,

Milton Mazzarri

[José Valim]

Thanks Brian for the reports!

Given there is some uncertainty here, we also recommend you to consider other GSoC projects that you may be interested on, inside or outside the BEAM community. If it turns out that this project is a dead end, you should have backups. :)

José Valim

www.plataformatec.com.br

Founder and 

Director of R&D

[b...@pdx.edu]

Alright, thank you for the feedback and suggestions. I'll investigate further and report back.

Brian Ginsburg
brianginsburg.com

[b...@pdx.edu]

Hi all,

I think I will step back from this project. Some other opportunities have come up for me, and I would not be able to devote sufficient time to the project.

If another GSoC student or community member decides to take this on, I am happy to share my thoughts on it.

Brian Ginsburg
brianginsburg.com

On Saturday, February 24, 2018 at 2:37:04 PM UTC-8, José Valim wrote: