How to add an .exs script to docs?

Questions / Help
, ,
1

Hello, I have an .exs script with Mix.install in a repo and I’d like to include it in the docs. Putting it into extras throws an error that only markdown files are allowed. What’s the best way to include the script in the docs?

2 Likes
2

You’re trying to show the contents of the file in the docs? Would @moduledoc "#{File.read("script.exs")}" work?

2 Likes
3

AFAIK, while Earmark supports custom processing allowing you to do things like this, ExDoc does not.

I’d use @external_resource with @benwilson512’s approach to insert script code somewhere into module/function docs, or rework the script into a Livebook (which is publishable by ExDoc).

2 Likes
4

Would @moduledoc “#{File.read(“script.exs”)}” work?

Yeah, thought about it, but to me it doesn’t really fit in the moduledoc.

I asked if exs could be supported, but apparently it cannot ¯\_(ツ)_/¯ so I’m going to just link to GitHub :wink:

1 Like
5

I’m sure you have your reasons but why the hard requirement to have it as an .exs? If it’s a sample file for people to run on their local machines, what’s wrong with putting it code fences in markdown? That way you get the copy-to-clipboard button and users can just paste into their editor.

6

It’s not a hard requirement, it just feels right to me to have an exs script in an exs file. It’s not a big deal anyway :slight_smile:

1 Like