Examples as ExDocs

[l3nz]

As the point of this library is to generate SVG, and Elixir supports code evals, it should be very easy to generate ExDocs for a "samples" module that embeds:

• the source code needed to generate such examples
• the resulting SVG graph

This is better IMHO compared to having images, because if you make a change in the library, it is immediately reflected on all the graphs generated. Also, examples are where they are supposed to be, in the documentation! And, thanks to issue #74 we have a number of examples to get started on.

This could also be useful for generating automated formal tests, e.g that the SVG generated is always formally valid (this could be done I think with Floki).

I have used this approach to check different cases the LogLinearScale and found it quite useful. So it would not be much work sending a PR for it, if interested.

[l3nz]

You can see what I did here: https://github.com/l3nz/contex/tree/exdoc_examples_82/lib/chart/gallery

[mindok]

Ok - that's pretty cool! I think that absolutely nails #74. A PR would be much appreciated! I couldn't push a couple of changes to "improve" SVG styling (or at least make it consistent with the poorly styled website), but the following changes will achieve that:

1. replace defp docs in mix.exs with the following:

  defp docs do
    [
      main: "Contex",
      logo: "assets/logo.png",
      assets: "lib/chart/gallery/assets",
      before_closing_head_tag: &docs_before_closing_head_tag/1
    ]
  end

  # Injects reference to contex.css into documentation output
  # See https://medium.com/@takanori.ishikawa/customize-how-your-exdoc-documentation-looks-a10234dbb4c9
  defp docs_before_closing_head_tag(:html) do
    ~s{<link rel="stylesheet" href="assets/contex.css">}
  end
  defp docs_before_closing_head_tag(_), do: ""

2. add a css file at lib/charts/gallery/assets/contex.css with the following CSS:

/* Styling for tick line */
.exc-tick line {
  stroke: rgb(207, 207, 207);
  ;
}

/* Styling for tick text */
.exc-tick text {
  fill: grey;
  stroke: none;
  font-size: 0.5rem;
  font-family: Helvetica, Arial, sans-serif;
}

/* Styling for axis line */
.exc-domain {
  stroke: rgb(207, 207, 207);
}

/* Styling for grid line */
.exc-grid {
  stroke: lightgrey;
}

/* Styling for outline of colours in legend */
.exc-legend {
  stroke: black;
}

/* Styling for text of colours in legend */
.exc-legend text {
  fill: grey;
  font-size: 0.8rem;
  stroke: none;
  font-family: Helvetica, Arial, sans-serif;
}

/* Styling for title & subtitle of any plot */
.exc-title {
  fill: darkslategray;
  font-size: 1.3rem;
  stroke: none;
  font-family: Helvetica, Arial, sans-serif;
}

.exc-subtitle {
  fill: darkgrey;
  font-size: 0.7rem;
  stroke: none;
  font-family: Helvetica, Arial, sans-serif;
}

/* Styling for label printed inside a bar on a barchart */
.exc-barlabel-in {
  fill: white;
  font-size: 0.8rem;
  font-family: Helvetica, Arial, sans-serif;
}

/* Styling for label printed outside of a bar (e.g. if bar is too small) */
.exc-barlabel-out {
  fill: grey;
  font-size: 0.7rem;
  font-family: Helvetica, Arial, sans-serif;
}

[l3nz]

I'll add your changes so that everything is in the same patch. I'll also add the examples in #74. When done, maybe you can make a release so we can see how it looks like on hexdocs.

[l3nz]

I have a PR but there are a couple of files too many (for some reason it keeps adding the files we just committed).

[mindok]

This is great work thanks @l3nz.

I squash merged the PR and all the changes appear to be in properly. Git is smart enough to handle the duplicate commits.

I'm no git expert, but you may need to fetch from upstream into your fork to get the commits from here, then pull updates to your local branch, then make a new branch. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork