Find a documentation generator for written libraries

[wende]

Since we no longer use Elm package system, we need something to generate documentation out of elm-make --docs json file. Preferably something that would create github markdown documentation file

[wende]

@Baransu Did you manage to make any progress in finding a solution to this?

[MartinKavik]

@wende I searched a bit and didn't find anything useful. But I can write something during next weeks - could you post an example of generated json file and corresponding documentation file? And some specifications: Language (Elixir, JS, ...), Type (Console app, module, web API...), .. ?

[baransu]

I haven't but I can write something. Do you want it to be in any specific language or is JS ok for you?

[wende]

@MartinKavik Crucial part would be not to include any additional (unneeded) libraries to the equation. So anything Node.js/Elm(?)/Elixir/Erlang compliant would fit. @Baransu stepped forward with a proposal to write it in ClojureScript which I think is a phenomenal idea since it's both very nice functional language and also seamlessly compliant to node.js.

Generally the idea is to achieve something as close to Hex docs or Elm package docs as possible in a single .md file. Obviously making it more specific to cover Elmchemy function and its Elixir equivalent would be a cool bonus.

So probably something like:

Modules

FizzModule --- This will link to an anchor

FizzModule

Module that makes sure for your fizzes to stay in order and perfectly un-buzzed

• fizzbuzz : Int -> String

• buzzfizz : String -> Int

  fizbuzz : Int -> String

      Fizzes the buzzes and buzzfizzes

  fizzbuzz 3 = "fizz"
  fizzbuzz 5 = "fizzbuzz"

  \<\/> <--- link to source

  buzfizz : String -> Int

      Buzzfizzess the fizz out of baz

  buzzfizz "fiz" = 3
  buzzfizz "fizzbuzz" = 5

  \<\/>

[MartinKavik]

@wende I'm not sure introducing ClojureScript is a good idea - it requires new prerequisite: Java (clojurescript.org/guides/quick-start) and mainly it will be harder to contribute to this project - for example I have to develop in PHP / NodeJS / C# / C++ / .. in work and I am learning Elixir + Elm in nights, so I haven't got time for learning another language.

My suggestion: elm-make is a console app so I think the best approach will be make docs generator also as a console app - maybe with Escript. Language Elixir or ideally Elm (is it possible to already use IO modules from Elm?)

[wende]

@MartinKavik It's a small project and doesn't necessarily have to be tightly coupled with Elchemy. It can be totally independent as long as it fits our needs.

Using ClojureScript wouldn't require JVM to be installed on users machine. Only for development, since the output of Boot for CLJS is a node.js file ( good read )

It's just a cool idea. It's not like this sub-project is a complex endeavour. My assumption is a project like that if done properly will be readable straight away no matter what language it is written in.

It could be Escript, but that would be limiting in terms of this sub-project being able to shine independently (not many users have BEAM installed on their machines right away) And I believe there is more projects like ours that would like a markdown documentation generator.

Anything that runs without having to install dependencies should work. So for Unix users (which I believe are our target) that would be anything that can be installed by npm gem or pip

[wende]

And no. It's not possible to use IO modules or any effects yet. I mean... It is doable, just not advised since it would be ugly and against pure code conventions.

Elchemy-effects is definitely first on a list to be designed and implemented and it's probably going to be very similar to what Elm does right now, with - hopefully - some templates to make it easier since Elm-effects isn't trivial and generally very steep in terms of learning curve which I would like to avoid at all costs (Think of it like more things similar to Html.beginnerProgram and less of effect module where {} exposing (..)

[MartinKavik]

@wende Thanks for the explanation, for independent project it will be good choice. Well, at least I can be one of Windows testers :)

[wende]

@MartinKavik Oooh. That's going to be valuable for testing. It's hard to find developers on Windows in niche languages these days :D

[wende]

I think something like JsDox but universal in terms of input being JSON data file instead of JavaScript file with JSDocs comments would be perfect (within a reasonable amount of complexity and dedication obviously)

[baransu]

I've started working on https://github.com/baransu/elm-docs. It's still in progress and has few missing features. Posting it here to let you know. I haven't had time to work on it recently but in the following week I'll probably find some time add missing basic features.

[baransu]

@wende Just released elm-docs 0.2.0. It has support for global and module table of content. Here you can find example documentation generated for wende/elchemy-core.

[wende]

@Baransu looks really nice. I wonder how hard would it be to include a link to a source in each of those. Have you got any idea how could that be done?

[baransu]

elm-docs just got published to npm. If you have any bugs or feature requests feel free to open issue at github repo 😊.

[wende]

Ok. Every new card or suggestion will be now posted on Baransu/elm-docs