Iris

Iris is an Elixir library to help visualize your codebase. Iris also plots function call paths as an interactive graph in your browser.

Iris aims to reduce the time taken to skim through an Elixir codebase by rendering an interactive GUI displaying the constituent applications, modules, functions and function call paths, even documentation!

Iris for Elixir screenshot

The following features are implemented.

List all Applications in elixir lib
List all Modules in an application
List all functions in an application
Generate & View inbound and outbound calls from a selected function
Click on outbound call function to expand the function and view its outbound calls
Show Function documentation for both public and private functions and private macros
Show Module documentation
Detect and denote recursive functions with a recursion icon
Detect and denote functions that have documentation with a docs icon
Detect and denote Macros with a macro icon

Installation

The package can be installed by adding iris to your list of dependencies in mix.exs:

def deps do
  [
    {:iris, "~> 0.2.1"}
  ]
end

Hex package located at https://hexdocs.pm/iris.

Usage

Execute the following command after ensuring iris is added to your dependency list.

mix iris

For more verbose output use the verbose flag as such:

mix iris -v
mix iris --verbose

To link the generated iris GUI in documentation generated by ex_doc:

Add an empty IrisUI.md in the root directory of the project
Add IrisUI.md to the extras section of docs in mix.exs. See example
Execute mix iris.docs
You will find a link to IrisUI in the Pages section to irisui.html
In addition, you can alias mix docs to mix iris.docs to include the generated UI when publishing to hex. See aliases in mix.exs.

For writing documentation on private functions and rendering it in UI:

Iris supports adding the @idoc attribute prior to a private function definition. The documentation is rendered in UI in the same way ExDoc output is rendered. For example:

defmodule Test do

use IrisDoc # this statement is needed for using @idoc

  @idoc ~S"""
    This is documentation for private functions
  """
  defp private_function() do
    ....
  end

end

When the @idoc attribute is added to any other definitions a clear error is printed as such:

== Compilation error in file lib/iris/core.ex ==
** (CompileError) lib/iris/core.ex: @idoc supports only private functions defined in the module. Using @idoc before `def build/1` is not supported.
    lib/iris_doc.ex:41: IrisDoc.on_definition/6
    lib/iris/core.ex:10: (module)

Interactive Demo

HexDocs hosts the Iris GUI for this project! generated by mix iris.docs

Find the interactive UI at HexDocs -- https://hexdocs.pm/iris/irisui.html

Known Limitations

Functions passed as parameters and invoked using the dot notation are not fully supported
Lambdas are not fully supported
All external function calls are not rendered by default, however there should be a toggle for this in the next version of this library
- External functions refers to Elixir/Erlang modules such as Keyword, Path, Enum, etc.

Contribution

If you encounter any issue, raise a github issue with a minimal example that reproduces the issue.

This project implementation can be improved a lot, pull requests that improve the codebase/address any issues are welcome.

License

Iris source code is released under the Apache 2 License.

Any content of Iris, or any content generated by any "Derivative Works" (as specified in the Apache 2 License), must include a direct, and visible link to the Iris repository on each rendered material.

This project is heavily inspired by ExDoc and uses some of its source code in generating and viewing documentation. Documentation views contain direct, readable and visible links to the ExDoc repository as specified by the license. The icon used to denote recursive functions is from Grommet.

Next Page → Changelog