Serving Docs from within an App

Questions / Help
,
1

I thought it would be a good idea to serve my documentation for a client through a route in the application, I didn’t think it would be a good idea to just give them a folder full of html files and the epub file ex_doc generates is not styled nearly up to par in my opinion.

So I generated my documentation, created a resources "/", DocsController route, (painfully) manually converted each html file into an html.eex extension and moved the entire docs folder within templates. All really simple but I feel like there is a better way to do all of this and probably a few improvements I could make otherwise if anyone has any suggestions I appreciate it.

My controller looks like:

def index(conn, _params) do
  render(conn, "index.html")
end

def show(conn, %{"id" => id}) do
  render(conn, id)
end

Currently trying to get the styling and sidebar from /dist to correctly render.

1 Like
2

Why not let a dedicated http server like nginx serve the static HTML files?

3

I’ve this for development in my endpoint.ex:

  # Serve at "/doc" the static files from ex_doc.
  if Mix.env() == :dev do
    plug Plug.Static, at: "/docs", from: "doc", gzip: false

    plug Plug.Static, at: "/coverage", from: "cover", gzip: false
  end

only issue is that it’s missing redirect from /docs => /docs/index.html

8 Likes
4

I’ve been trying to avoid using something like nginx for simplicity. What would the benefits be?

5

Significantly faster static file hosting, easier SSL updating, able to host multiple servers on the same port, few other things, you lose HTTP2 if that matters though. :slight_smile:

2 Likes
6

But if you’re not serving too many static files/getting a lot of requests for these docs than I think it probably won’t be worth it.

1 Like
7

Exactly. I don’t mess with nginx for little things. I do use it heavily when I use lots of subdomains or hosting lots of different applications in subpaths on a single server though. :slight_smile:

2 Likes
8

Definitely. I usually use nginx when I reuse a singular small-ish server for a number of purposes. F.ex. I’ve had 3 separate project’s reporting subsystems hosted on such a server, and then one day I figured I’ll just put 10+ Swagger / ex_doc documentation packages there because they are rarely used and have practially zero footprint.

For a quick solution, what @LostKobrakai suggested is the best course of action.

1 Like