├── .gitignore
├── CHANGELOG.md
├── LICENSE.md
├── README.md
├── config
└── config.exs
├── lib
├── docset.ex
├── docset
│ └── sqlite.ex
├── ex_dash.ex
├── injector.ex
├── injector
│ ├── callback.ex
│ ├── function.ex
│ ├── macro.ex
│ └── type.ex
├── mix
│ └── tasks
│ │ └── dash.ex
└── store.ex
├── mix.exs
├── mix.lock
└── test
├── ex_dash_test.exs
├── injector_test.exs
├── mix
└── tasks
│ └── dash_test.exs
├── page_with_callbacks.html
└── test_helper.exs
/.gitignore:
--------------------------------------------------------------------------------
1 | # The directory Mix will write compiled artifacts to.
2 | /_build
3 |
4 | # If you run "mix test --cover", coverage assets end up here.
5 | /cover
6 |
7 | # The directory Mix downloads your dependencies sources to.
8 | /deps
9 |
10 | # Where 3rd-party dependencies like ExDoc output generated docs.
11 | /doc
12 |
13 | # Ignore .fetch files in case you like to edit your project deps locally.
14 | /.fetch
15 |
16 | # If the VM crashes, it generates a dump, let's ignore it too.
17 | erl_crash.dump
18 |
19 | # Also ignore archive artifacts (built via "mix archive.build").
20 | *.ez
21 |
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | # 0.1.6 updated ex_doc dep, test fix
2 |
3 | # 0.1.5 Smart Defaults
4 |
5 | The `--open` flag is now more of a 'force' open. When `mix docs.dash` is called, the docset is opened automatically, unless a docset with the exact name already exists (in that case, the docs update under the hood, but do not need to be re-opened in Dash for the updates to be realized).
6 |
7 | The `--name NAME` param now defaults to setting umbrella project names to the result of `File.cwd!() |> Path.basename()`, as this is likely the desired project name anyway.
8 |
9 | An `--abbr ABBR` option can be passed to set a custom abbreviation. This can also be edited in Dash's preferences pane by hand. This only works when the docset is first added to Dash - after that, it must be updated via Dash or fully removed and readded.
10 |
11 | # 0.1.4 tweak margins to match elixir docs
12 |
13 | # 0.1.3 fix app-name overwrite bug
14 |
15 | # 0.1.2 `--name NAME` and Umbrella App handling
16 |
17 | # 0.1.1 auto-open docset
18 |
19 | Add `--open` to auto-open the generated docset.
20 |
21 | `mix docs.dash --open`
22 |
23 | # 0.1.0 initial release
24 |
25 | `mix docs.dash`
26 |
--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | Copyright 2017 Russell Matney
2 |
3 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4 |
5 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6 |
7 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
8 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # ExDash
2 |
3 | ExDash seamlessly integrates the docs in your local elixir projects with your Dash docs.
4 |
5 | ExDash provides a mix task that rebuilds a Dash Docset for your local Elixir project.
6 |
7 | You can read more about the intended doc-searching workflow [in this blog post](https://medium.com/@russmatney/exdash-internal-elixir-docs-integrated-with-dash-434245fc8023).
8 |
9 |
10 | ### Quick Start
11 |
12 | 1. Add `{:ex_dash, "~> 0.1", only: :dev},` to your mix.exs deps
13 | 1. Run `mix docs.dash`
14 | 1. Viola! Your docs are now searchable in [Dash](https://kapeli.com/dash)
15 |
16 |
17 | ## The Dream
18 |
19 | The [Alfred](https://www.alfredapp.com/) + [Dash](https://kapeli.com/dash) integration
20 | for fast Elixir doc searching has become an integral part of our workflow at [Urbint](https://github.com/urbint).
21 |
22 | Once our app reached a certain size,
23 | we wanted to be able to search our internal documentation as easily as the public Hex docs.
24 |
25 | Being able to dogfood our own @moduledocs and function @docs helps us keep code quality higher.
26 |
27 | ExDash is intended to make that easier.
28 |
29 | ## Installation
30 |
31 | The package can be installed
32 | by adding `ex_dash` to your list of dependencies in `mix.exs`:
33 |
34 | ```elixir
35 | def deps do
36 | [
37 | {:ex_dash, "~> 0.1.0"},
38 | ]
39 | end
40 | ```
41 |
42 | ### Dependencies
43 |
44 | Dash Docsets include a SQLite table, and as such,
45 | this task expects `sqlite3` to be available.
46 |
47 | ```
48 | brew install sqlite3
49 | ```
50 |
51 | ## Usage
52 |
53 | ExDash currently provides a mix task that rebuilds the docset for your local app.
54 |
55 | ```
56 | mix docs.dash
57 | ```
58 |
59 | If the docset is being built for the first time,
60 | this command will finish by opening the docset via Dash.
61 | If the docset already exists locally,
62 | this command will assume that you are updating your local docs.
63 |
64 | Options:
65 |
66 | - `--open`: force the generated docset to open in dash
67 | - `--name`: Overwrite the project name when naming the docset.
68 | The name defaults to the project name, or for umbrella apps,
69 | the name of the directory.
70 | - `--abbr`: Overwrite the abbreviation for searching the docs.
71 | Defaults to the first two characters of the project name.
72 | Note that changing the abbreviation of the app requires
73 | deleting the docset entirely from Dash (via the preferneces pane)
74 | and likely running `mix docs.dash --open` to force the docset to re-index.
75 |
76 | # Hacking ExDocs into Dash Docs
77 |
78 | The goal for this project is to provide documentation for your local app
79 | to the same resource as the rest of your Docs.
80 | We want the docs to be indistinguishable from Elixir's source and Hex's docsets.
81 |
82 | As such, this task builds the full docs using ExDoc,
83 | then scrapes and find/replaces those pages into a similar (hopefully identical) style to those downloaded from Hex.
84 |
85 | Dash docsets require:
86 |
87 | - a SQLite database for search
88 | - Dash "anchors" on the doc pages to populate the Table of Contents per page
89 |
90 | See `ExDash.Docset` and `ExDash.Injector` for more.
91 |
92 | If there are other Dash features you'd like supported,
93 | please open a PR or an Issue!
94 |
95 | # Much thanks to the Elixir Community
96 |
97 | This project at the start borrowed heavily from work done [by @JonGretar on ExDocDash](https://github.com/JonGretar/ExDocDash). Much thanks to Jon's code as well as [ExDoc](https://github.com/elixir-lang/ex_doc), as they both made this problem much easier to solve. A break from Jon's project was made in favor of matching the style of documents built by ExDoc. Rather than writing and styling our own templates, this just builds the ExDoc docs and hacks them into a Docset.
98 |
--------------------------------------------------------------------------------
/config/config.exs:
--------------------------------------------------------------------------------
1 | # This file is responsible for configuring your application
2 | # and its dependencies with the aid of the Mix.Config module.
3 | use Mix.Config
4 |
5 | # This configuration is loaded before any dependency and is restricted
6 | # to this project. If another project depends on this project, this
7 | # file won't be loaded nor affect the parent project. For this reason,
8 | # if you want to provide default values for your application for
9 | # 3rd-party users, it should be done in your "mix.exs" file.
10 |
11 | # You can configure for your application as:
12 | #
13 | # config :ex_dash, key: :value
14 | #
15 | # And access this configuration in your application as:
16 | #
17 | # Application.get_env(:ex_dash, :key)
18 | #
19 | # Or configure a 3rd-party app:
20 | #
21 | # config :logger, level: :info
22 | #
23 |
24 | # It is also possible to import configuration files, relative to this
25 | # directory. For example, you can emulate configuration per environment
26 | # by uncommenting the line below and defining dev.exs, test.exs and such.
27 | # Configuration from the imported file will override the ones defined
28 | # here (which is why it is important to import them last).
29 | #
30 | # import_config "#{Mix.env}.exs"
31 |
--------------------------------------------------------------------------------
/lib/docset.ex:
--------------------------------------------------------------------------------
1 | defmodule ExDash.Docset do
2 | @moduledoc """
3 | Responsible for building the structure, SQLite DB, and Info.plist of a Dash Docset.
4 |
5 | """
6 |
7 | alias ExDash.Docset.SQLite
8 | alias ExDoc.Formatter.HTML.Autolink
9 | alias ExDash.Store
10 |
11 | @doc """
12 | build/2 converts a list of project nodes and a config into a Dash Docset,
13 | and writes that docset to your `/doc` dir.
14 |
15 | * takes a list of project_nodes and a config
16 | * initializes the directory structure and SQLite DB
17 | * iterates over the project nodes while writes metadata to the DB
18 | * writes content to the Info.plist
19 |
20 | """
21 | @spec build(list, ExDoc.Config.t) :: {config :: ExDoc.Config.t, docset_path :: String.t}
22 | def build(project_nodes, config) do
23 | {docset_docpath, database_path, docset_root_path} =
24 | init_docset(config)
25 |
26 | config =
27 | %{config | output: docset_docpath}
28 |
29 | build_sqlite_db(project_nodes, config, database_path)
30 |
31 | write_plist(config)
32 |
33 | {config, docset_root_path}
34 | end
35 |
36 | defp init_docset(config) do
37 | output = Path.expand(config.output)
38 |
39 | docset_filename =
40 | case config.version do
41 | "dev" ->
42 | "#{config.project}.docset"
43 | version ->
44 | "#{config.project} #{version}.docset"
45 | end
46 |
47 | docset_root = Path.join(output, docset_filename)
48 | docset_docpath = Path.join(docset_root, "/Contents/Resources/Documents")
49 | docset_sqlitepath = Path.join(docset_root, "/Contents/Resources/docSet.dsidx")
50 |
51 | is_new_docset? =
52 | not(File.exists?(docset_root))
53 |
54 | Store.set(:is_new_docset, is_new_docset?)
55 |
56 | {:ok, _} = File.rm_rf(docset_root)
57 | :ok = File.mkdir_p(docset_docpath)
58 |
59 | {docset_docpath, docset_sqlitepath, docset_root}
60 | end
61 |
62 | defp build_sqlite_db(project_nodes, config, database_path) do
63 | SQLite.create_index(database_path)
64 |
65 | Autolink.all(project_nodes, ".html", config.deps)
66 | |> Enum.map(&index_node(&1, database_path))
67 | end
68 |
69 | defp index_node(node, database) do
70 | database
71 | |> SQLite.index_item(node.id, "Module", "#{node.id}.html")
72 |
73 | node.docs
74 | |> Enum.each(&index_sub_node(&1, node.id, database))
75 |
76 | node.typespecs
77 | |> Enum.each(&index_sub_node(&1, node.id, database))
78 | end
79 |
80 | defp index_sub_node(%ExDoc.FunctionNode{} = node, module, database) do
81 | type =
82 | case node.type do
83 | :def -> "Function"
84 | :defmacro -> "Macro"
85 | :defcallback -> "Callback"
86 | _ -> "Record"
87 | end
88 |
89 | database
90 | |> SQLite.index_item("#{module}.#{node.id}", type, "#{module}.html##{node.id}")
91 | end
92 |
93 | defp index_sub_node(%ExDoc.TypeNode{} = node, module, database) do
94 | database
95 | |> SQLite.index_item("#{module}.#{node.id}", "Type", "#{module}.html##{node.id}")
96 | end
97 |
98 | defp index_sub_node(%ExDoc.ModuleNode{type: :exception} = node, _module, database) do
99 | database
100 | |> SQLite.index_item(node.id, "Exception", "#{node.id}.html")
101 | end
102 |
103 | defp log(path) do
104 | cwd = File.cwd!
105 | Mix.shell.info [:green, "* creating ", :reset, Path.relative_to(path, cwd)]
106 | path
107 | end
108 |
109 | defp write_plist(config) do
110 | content =
111 | info_plist_content(config)
112 |
113 | "#{config.output}/../../Info.plist" |> log |> File.write(content)
114 | end
115 |
116 | @info_plist_template """
117 |
118 |
119 |
120 |
121 | CFBundleIdentifier {{CONFIG_PROJECT}}-{{CONFIG_VERSION}}
122 | CFBundleName {{CONFIG_PROJECT}} {{CONFIG_VERSION}}
123 | DocSetPlatformFamily {{CONFIG_PROJECT_ABBREV}}
124 | isDashDocset
125 | isJavaScriptEnabled
126 | dashIndexFilePath index.html
127 | DashDocSetFamily dashtoc
128 |
129 |
130 | """
131 |
132 | defp info_plist_content(%{project: name, version: version}) do
133 | version =
134 | case version do
135 | "dev" ->
136 | ""
137 | version ->
138 | version
139 | end
140 |
141 | abbreviation =
142 | case Store.get(:abbreviation) do
143 | nil ->
144 | name |> String.slice(0, 2)
145 |
146 | abbr ->
147 | abbr
148 | end
149 |
150 | @info_plist_template
151 | |> String.replace("{{CONFIG_PROJECT}}", name)
152 | |> String.replace("{{CONFIG_VERSION}}", version)
153 | |> String.replace("{{CONFIG_PROJECT_ABBREV}}", abbreviation)
154 | end
155 |
156 | end
157 |
--------------------------------------------------------------------------------
/lib/docset/sqlite.ex:
--------------------------------------------------------------------------------
1 | defmodule ExDash.Docset.SQLite do
2 | @moduledoc """
3 | Execute an SQL query using the sqlite3 command line utility.
4 |
5 | """
6 |
7 | defmodule SQLError do
8 | defexception message: "default message", exit_code: 1
9 | end
10 |
11 | @type query :: String.t
12 | @type query_result :: String.t
13 |
14 | @spec create_index(String.t) :: :ok
15 | def create_index(db) do
16 | exec!(db, "CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT);")
17 | exec!(db, "CREATE UNIQUE INDEX anchor ON searchIndex (name, type, path);")
18 | :ok
19 | end
20 |
21 | @spec index_item(Map.t, String.t, String.t, String.t) :: :ok
22 | def index_item(db, name, type, path) do
23 | query =
24 | "INSERT OR IGNORE INTO searchIndex(name, type, path) VALUES ('#{name}', '#{type}', '#{path}');"
25 |
26 | exec!(db, query)
27 | :ok
28 | end
29 |
30 |
31 | @doc ~S"""
32 | Executes given query onto a database.
33 |
34 | {:ok, results} = ExDocDash.SQLite.exec("my.db", "SELECT * from something")
35 | IO.format("Results: #{results}")
36 |
37 | """
38 | @spec exec!(String.t, query) :: query_result
39 | def exec!(database, query) do
40 | args =
41 | [database, query]
42 |
43 | options =
44 | [stderr_to_stdout: true]
45 |
46 | case System.cmd("sqlite3", args, options) do
47 | {results, 0} ->
48 | results
49 |
50 | {"Error: " <> error, exit_code} ->
51 | raise(SQLError, message: error, exit_code: exit_code)
52 |
53 | {error, exit_code} ->
54 | raise(SQLError, message: "#{error}", exit_code: exit_code)
55 | end
56 | end
57 |
58 | end
59 |
--------------------------------------------------------------------------------
/lib/ex_dash.ex:
--------------------------------------------------------------------------------
1 | defmodule ExDash do
2 | @moduledoc """
3 | ExDash provides a `Formatter` and mix task for converting your elixir project into a Dash docset.
4 |
5 | """
6 |
7 | alias ExDash.{Injector,Docset,Store}
8 |
9 | @doc """
10 | A run function that is called by ExDoc.
11 |
12 | """
13 | @spec run(list, ExDoc.Config.t) :: {list, ExDoc.Config.t}
14 | def run(project_nodes, config) when is_map(config) do
15 | name =
16 | Store.get(:name)
17 |
18 | config =
19 | cond do
20 | not is_nil(name) ->
21 | %{config | project: name}
22 |
23 | config.project == "" ->
24 | %{config | project: default_umbrella_project_name()}
25 |
26 | true ->
27 | config
28 | end
29 |
30 | {config, docset_root_path} =
31 | Docset.build(project_nodes, config)
32 |
33 | ExDoc.Formatter.HTML.run(project_nodes, config)
34 |
35 | transform_ex_docs_to_dash_docs(config.output)
36 |
37 | docset_root_path
38 | end
39 |
40 | defp transform_ex_docs_to_dash_docs(output_docs_dir, ends_with \\ ".html") do
41 | File.ls!(output_docs_dir)
42 | |> Stream.filter(&String.ends_with?(&1, ends_with))
43 | |> Stream.map(&Path.join(output_docs_dir, &1))
44 | |> Enum.map(&Injector.inject_all/1)
45 | end
46 |
47 | defp default_umbrella_project_name() do
48 | File.cwd!() |> Path.basename()
49 | end
50 |
51 | end
52 |
--------------------------------------------------------------------------------
/lib/injector.ex:
--------------------------------------------------------------------------------
1 | defmodule ExDash.Injector do
2 | @moduledoc """
3 | Injector sets Dash Anchors and makes style tweaks to passed ExDoc HTML files.
4 |
5 | Dash Anchors are used within Dash to build the Table of Contents per page.
6 |
7 | Currently supported:
8 |
9 | - Types
10 | - Functions
11 | - Macros
12 | - Callbacks
13 |
14 | Style tweaks include hiding the sidebar and padding tweaks to match Dash's Hex Doc styles.
15 |
16 | """
17 |
18 | alias Floki
19 | alias ExDash.Injector.{Type,Function,Callback,Macro}
20 |
21 | @type doc_path :: String.t
22 | @type id :: String.t
23 | @type html_content :: String.t
24 |
25 | @dash_anchor_injectors [Type, Function, Callback, Macro]
26 |
27 | # Injector callbacks
28 | @callback find_ids(html_content) :: [id]
29 | @callback match_and_anchor(id) :: [{String.t, String.t}]
30 |
31 |
32 | @doc """
33 | inject_all/1 takes a path to an html file and runs some injections over it.
34 |
35 | The updated html is then re-written to the same path.
36 |
37 | """
38 | @spec inject_all(doc_path) :: none
39 | def inject_all(doc_path) do
40 | updated_content =
41 | doc_path
42 | |> File.read!()
43 | |> inject_dash_anchors()
44 | |> inject_style_tweaks()
45 |
46 | File.write!(doc_path, updated_content)
47 | end
48 |
49 | @spec inject_dash_anchors(html_content) :: html_content
50 | defp inject_dash_anchors(html_content, dash_anchor_injectors \\ @dash_anchor_injectors) do
51 | dash_anchor_injectors
52 | |> Enum.reduce(html_content, fn injector, html_content ->
53 | meta_type_ids =
54 | injector.find_ids(html_content)
55 |
56 | match_and_anchors =
57 | meta_type_ids
58 | |> Enum.map(&injector.match_and_anchor/1)
59 |
60 | find_and_replace_in_html(html_content, match_and_anchors)
61 | end)
62 | end
63 |
64 | @ex_doc_html_match_and_replace [
65 | {
66 | "