elm-book icon indicating copy to clipboard operation
elm-book copied to clipboard

Generating ElmBooks based on doc comments

Open Orasund opened this issue 2 years ago • 1 comments

In The Roadmap you write

Generating ElmBooks based on doc comments – the same that are used to generate docs on elm-packages. This could allow published elm packages to automatically have their own ElmBook with example codes turning into live components and no code duplication.

Is this still up for grabs? I'm currently interested in anything related to generating content and am currently investigating different ways of doing so. This task might be a good way to explore various possibilities.

Some technologies I want to explore using this task:

  • Elm-codegen - generates code using Elm
  • Elm-pen - generates code using Moustache Files & Json
  • elm-posix - lets you read & write files using node.js

Orasund avatar Oct 19 '22 04:10 Orasund

I actually have already something to show: Checkout this Documentation You find the code here. The steps needed to get to the documentation where the following:

  1. Create an Elm file containing the documentation (See ElmBook.Gen.Doc.Module inside the generated folder)
  2. Create Elm-Book chapters (See ElmBook.Docs in src)
  3. Copy the created files into the main source code folder (this step is currently missing)
  4. Create your Elm-Book like usual and include ElmBook.Docs.chapters in the list of chapters.

What's missing is the CLI that automates these processes. I'm also not sure if I should create a new repository for this or if it should live inside this repository...?

Orasund avatar Oct 21 '22 18:10 Orasund