Readmix.Docs (readmix v0.3.0)

Utilities for generating documentation for Readmix generators.

Summary

Functions

Returns the content of a rdmx:section block from the given path.

Generates documentation for the actions registered with Readmix.Generator.action/2.

Generates documentation for actions defined as a keyword list.

Functions

extract_section(path, name)

Returns the content of a rdmx:section block from the given path.

The content is returned as iodata for inclusion in documentation and not as Readmix blocks for transformation. The blocks are not processed, the current content of the file is returned.

If you are using this function during compilation, it is recommended to declare the source file as an external resource.

Example

<!-- rdmx :section name="examples" -->
Here is how to use the awesome service...
<!-- rdmx /:section -->
defmodule AwesomeService do
  @external_resource "guides/services/awesome.md"

  @moduledoc """
  This is an awesome service.

  ### Examples

  #{Readmix.Docs.extract_section("guides/services/awesome.md", "examples")}
  """
end

generate()

(macro)

Generates documentation for the actions registered with Readmix.Generator.action/2.

Example

defmodule MyGenerator do
  use Readmix.Generator

  action :greeting, params [name: :string, required: true]

  @moduledoc """
  A block generator

  #{Readmix.Docs.generate()}
  """

  def greeting(args, _) do
    {:ok, ["hello ", args[:name]]}
  end
end

generate(actions)

Generates documentation for actions defined as a keyword list.

defmodule MyGenerator do
  @behaviour Readmix.Generator

  @actions [
    greeting: [
      params [name: :string, required: true]
    ]
  ]

  @moduledoc """
  A block generator

  #{Readmix.Docs.generate(@actions)}
  """

  @impl true
  def actions, do: @actions

  @impl true
  def generate(:greeting, args, _) do
    {:ok, ["hello ", args[:name]]}
  end
end