Port ExDoc to Elm - Introduction and initial implementation

[Radcliffe Robinson]

Hey There,

I am Radcliffe Robinson, a second year Computer Science student at the University of The West Indies in Jamaica. 

I have taken an interest in the project to rewrite the javascript components and markdown concerns of ex_doc project because of its use of the Elm language/framework, which i learned on a whim recently and have used on one small project which is currently deployed and in use (code on my github here : https://github.com/Steams/Elm-TTSA-Carnival-Webapp, live application here : http://www.ttsacosmopolitan.com/)

Developing with Elm was an unexpectedly pleasant experience, providing me the smoothest, most reliably  and easily reasoned about web development workflows i have experienced.

I already had functional programming experience through Scala, and had come to appreciate the syntax and  purer functional nature of Elm (and through it, Haskell) and so was looking forward to utilizing it further. This is why i am excited for the opportunity to work on this project.

I have no prior experience with Elixir but am confident i will be able to learn enough of the language to be productive on the project.

I have examined the relevant parts of the ex_doc source code in order to determine an approach for slowly integrating an elm app into its components and have come up with the following approach:

1. create a elm application and integrate its compilation into the gulp build process, placing the compiled javscript file containing the Elm app into the priv/ex_doc/formatter/html/assets/dist so that it will be copied to the doc/dist folder when ex_doc is run.
2. In the header_template, import the elm app from the dist folder.
3. In the footer_template, initialize and embed the Elm app as well as pass in the sidebarNodes object as Elm Flags.

Using this process and embedding the elm app into individual html elements we can slowly upgrade individual components of the application while leaving other working parts untouched for the time being.

Using this process i have forked the repository and developed a working and runnable (albeit rushed and unpolished) replacement for the sidebar component in Elm as a proof of concept of this approach. Any feedback on the approach or implementation is appreciated. It can be inspected here https://github.com/Steams/ex-doc-Elm-Frontend.

I will be applying to multiple Gsoc projects but am primarily interested in this one so far.

I am, If given the opportunity, looking forward to working with the ex-doc team to make this project a success.

Best regards,

Radcliffe

[José Valim]

Welcome Radcliffe!

Yes, I don't think prior experience to Elixir will be a problem. You just need enough to understand how to manipulate the .eex templates, that generate HTML files, and your mentor will also be able to help you. There are other important points worth considering:

1. We don't need to stick with gulp if there are better tools for compiling Elm code

2. The project should be able to run offline. That's why today we generate and inject a JS file rather than using Ajax. You should consider how this restriction may impact your design

3. How is the testing situation with Elm? I believe the current code today has no tests and it would be nice to have a test suite to back it up

4. We would like to push much of the presentation and rendering to Elm and keep the HTML files literally for transporting of the data used by Elm

If you have any more questions, feel free to ask them!

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D