Misc doc changes (#29)

* Misc doc changes Besides other documentation changes, this commit ensures the generated HTML doc for HexDocs.pm will become the source of truth for this Elixir library and leverage on latest features of ExDoc. * Remove duplicate badge Co-authored-by: Dorgan <[email protected]>
doorgan · Oct 2, 2021 · c8be82d · c8be82d
1 parent 2251f4e
commit c8be82d
Show file tree

Hide file tree

Showing 8 changed files with 77 additions and 66 deletions.
diff --git a/.gitignore b/.gitignore
@@ -22,15 +22,12 @@ erl_crash.dump
 # Ignore package tarball (built via "mix hex.build").
 sourceror-*.tar
 
-# Temporary files for e.g. tests
-/tmp
+# Temporary files, for example, from tests.
+/tmp/
 
-# Compiled parser
+# Compiled parser.
 /src/*_parser.erl
 
-# Elixir LS files
-/.elixir_ls
-
-# Dialyzer plts
+# Dialyzer plts.
 /priv/plts/*
-!/priv/plts/.gitkeep
+!/priv/plts/.gitkeep
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,34 +1,39 @@
 # Changelog for Sourceror v0.8
 
-## v0.8.4
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v0.8.4 (2021-09-15)
 
 ### 1. Bug fixes
 
 - [Sourceror] `get_range/1` now properly handles naked AST lists, like the ones
   coming from partial keyword lists, or stabs like `a -> b`.
 
-## v0.8.3
+## v0.8.3 (2021-09-13)
 
 ### 1. Bug fixes
 
 - [Sourceror] `get_range/1` now handles partial keyword list syntax instead of
   crashing.
 
-## v0.8.2
+## v0.8.2 (2021-08-12)
 
 ### 1. Bug fixes
 
 - [Sourceror.Zipper] `down/1` now correctly uses `nil` as the right siblings if
   the branch node has a single child.
 
-## v0.8.1
+## v0.8.1 (2021-07-03)
 
 ### 1. Bug fixes
 
 - [Sourceror] `Sourceror.get_range/1` now correctly calculates the range when
   there is a comment in the same line as the node.
 
-## v0.8.0
+## v0.8.0 (2021-06-24)
 
 ### 1. Enhancements
 
@@ -42,7 +47,7 @@
 - [Sourceror] Now `Sourceror.get_range/1` will take the leading comments into
   account when calculating the range.
 
-## v0.7
+## v0.7.0 (2021-06-12)
 
 The changelog for v0.7 releases can be found [in the v0.7
 branch](https://github.com/doorgan/sourceror/blob/v0.7/CHANGELOG.md).
diff --git a/README.md b/README.md
@@ -1,40 +1,20 @@
+# Sourceror 🧙
+
 ![Github Actions](https://github.com/doorgan/sourceror/actions/workflows/main.yml/badge.svg?branch=main)
 [![Coverage Status](https://coveralls.io/repos/github/doorgan/sourceror/badge.svg?branch=main)](https://coveralls.io/github/doorgan/sourceror?branch=main)
-[![Hex.pm version](https://img.shields.io/hexpm/v/sourceror)](https://hex.pm/packages/sourceror)
+[![Module Version](https://img.shields.io/hexpm/v/sourceror.svg)](https://hex.pm/packages/sourceror)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/sourceror/)
+[![Total Download](https://img.shields.io/hexpm/dt/sourceror.svg)](https://hex.pm/packages/sourceror)
+[![License](https://img.shields.io/hexpm/l/sourceror.svg)](https://github.com/doorgan/sourceror/blob/master/LICENSE)
+[![Last Updated](https://img.shields.io/github/last-commit/doorgan/sourceror.svg)](https://github.com/doorgan/sourceror/commits/master)
 
-# Sourceror 🧙
+<!-- MDOC !-->
 
 Utilities to work with Elixir source code.
 
 **NOTICE:** This library is under heavy development. Expect frequent breaking
 changes until the first stable v1.0 release is out.
 
-## Documentation
-
-You can find Sourceror documentation on [Hex Docs](https://hexdocs.pm/sourceror/readme.html).
-
-## Examples
-
-You can find usage examples in the `examples` folder. You can run them by
-cloning the repo and running `elixir examples/<example_file>.exs`.
-
-You can also find documented examples you can run with [Livebook](https://github.com/elixir-nx/livebook)
-in the `notebooks` folder.
-
-## Contributing
-
-If you want to contribute to Sourceror, please check our
-[Contributing](https://github.com/doorgan/sourceror/blob/master/CONTRIBUTING.md)
-section for pointers.
-
-## Getting assistance
-
-If you have any questions about Sourceror or need assistance, please open a
-thread in the [Discussions](https://github.com/doorgan/sourceror/discussions)
-section.
-
-<!-- MDOC !-->
-
 ## Installation
 
 Add `:sourceror` as a dependency to your project's `mix.exs`:
@@ -119,7 +99,7 @@ formatter do the rest.
 
 Having the AST and comments as separate entities allows Elixir to expose the
 code formatting utilities without making any changes to it's AST, but also
-delegates the task of figuring out what's the most appropiate way to work with
+delegates the task of figuring out what's the most appropriate way to work with
 them to us.
 
 Sourceror's take is to use the node metadata to store the comments. This allows
@@ -166,19 +146,45 @@ Two metadata fields are added to the regular Elixir AST:
   ```
 
 Note that Sourceror considers leading comments to the ones that are found in the
-same line as a node, and trailing coments to the ones that are found before the
+same line as a node, and trailing comments to the ones that are found before the
 ending line of a node, based on the `end`, `closing` or `end_of_expression`
 line. This also makes the Sourceror AST consistent with the way the Elixir
 formatter works, making it easier to reason about how a given AST would be
 formatted.
 
-## License
+<!-- MDOC !-->
+
+## Documentation
+
+You can find Sourceror documentation on [Hex Docs](https://hexdocs.pm/sourceror/readme.html).
+
+## Examples
+
+You can find usage examples in the `examples` folder. You can run them by
+cloning the repo and running `elixir examples/<example_file>.exs`.
+
+You can also find documented examples you can run with [Livebook](https://github.com/elixir-nx/livebook)
+in the `notebooks` folder.
+
+## Contributing
+
+If you want to contribute to Sourceror, please check our
+[Contributing](https://github.com/doorgan/sourceror/blob/master/CONTRIBUTING.md)
+section for pointers.
+
+## Getting assistance
+
+If you have any questions about Sourceror or need assistance, please open a
+thread in the [Discussions](https://github.com/doorgan/sourceror/discussions)
+section.
+
+## Copyright and License
 
 Copyright (c) 2021 [email protected]
 
-Licensed under the Apache License, Version 2.0 (the "License"); you may not use
-this file except in compliance with the License. You may obtain a copy of the
-License at http://www.apache.org/licenses/LICENSE-2.0
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
 
 Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR

diff --git a/lib/sourceror.ex b/lib/sourceror.ex
@@ -1,5 +1,6 @@
 defmodule Sourceror do
-  @moduledoc "README.md"
+  @external_resource "README.md"
+  @moduledoc @external_resource
              |> File.read!()
              |> String.split("<!-- MDOC !-->")
              |> Enum.fetch!(1)

diff --git a/mix.exs b/mix.exs
@@ -1,14 +1,13 @@
 defmodule Sourceror.MixProject do
   use Mix.Project
 
-  @version "0.8.4"
   @repo_url "https://github.com/doorgan/sourceror"
+  @version "0.8.4"
 
   def project do
     [
       app: :sourceror,
       name: "Sourceror",
-      description: description(),
       version: @version,
       elixir: "~> 1.10",
       start_permanent: Mix.env() == :prod,
@@ -54,18 +53,15 @@ defmodule Sourceror.MixProject do
       {:credo, "~> 1.5", only: [:dev, :test], runtime: false},
       {:dialyxir, "~> 1.1", only: [:dev], runtime: false},
       {:ex_check, "~> 0.14.0", only: [:dev], runtime: false},
-      {:ex_doc, "~> 0.24.2", only: :dev, runtime: false},
+      {:ex_doc, ">= 0.0.0", only: :dev, runtime: false},
       {:excoveralls, "~> 0.10", only: [:test]},
       {:sobelow, "~> 0.8", only: :dev}
     ]
   end
 
-  defp description do
-    "Utilities to work with Elixir source code."
-  end
-
   defp package do
     [
+      description: "Utilities to work with Elixir source code.",
       licenses: ["Apache-2.0"],
       links: %{
         "GitHub" => @repo_url
@@ -75,11 +71,17 @@ defmodule Sourceror.MixProject do
 
   defp docs do
     [
-      main: "Sourceror",
+      extras: [
+        "CHANGELOG.md": [title: "Changelog"],
+        "CONTRIBUTING.md": [title: "Contributing"],
+        "LICENSE": [title: "License"],
+        "README.md": [title: "Overview"]
+      ],
+      main: "readme",
+      homepage_url: @repo_url,
       source_ref: @version,
       source_url: @repo_url,
-      homepage_url: @repo_url,
-      extras: ["README.md"]
+      formatters: ["html"]
     ]
   end
 end
diff --git a/mix.lock b/mix.lock
@@ -3,10 +3,10 @@
   "certifi": {:hex, :certifi, "2.6.1", "dbab8e5e155a0763eea978c913ca280a6b544bfa115633fa20249c3d396d9493", [:rebar3], [], "hexpm", "524c97b4991b3849dd5c17a631223896272c6b0af446778ba4675a1dff53bb7e"},
   "credo": {:hex, :credo, "1.5.6", "e04cc0fdc236fefbb578e0c04bd01a471081616e741d386909e527ac146016c6", [:mix], [{:bunt, "~> 0.2.0", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2.8", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "4b52a3e558bd64e30de62a648518a5ea2b6e3e5d2b164ef5296244753fc7eb17"},
   "dialyxir": {:hex, :dialyxir, "1.1.0", "c5aab0d6e71e5522e77beff7ba9e08f8e02bad90dfbeffae60eaf0cb47e29488", [:mix], [{:erlex, ">= 0.2.6", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "07ea8e49c45f15264ebe6d5b93799d4dd56a44036cf42d0ad9c960bc266c0b9a"},
-  "earmark_parser": {:hex, :earmark_parser, "1.4.13", "0c98163e7d04a15feb62000e1a891489feb29f3d10cb57d4f845c405852bbef8", [:mix], [], "hexpm", "d602c26af3a0af43d2f2645613f65841657ad6efc9f0e361c3b6c06b578214ba"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.15", "b29e8e729f4aa4a00436580dcc2c9c5c51890613457c193cc8525c388ccb2f06", [:mix], [], "hexpm", "044523d6438ea19c1b8ec877ec221b008661d3c27e3b848f4c879f500421ca5c"},
   "erlex": {:hex, :erlex, "0.2.6", "c7987d15e899c7a2f34f5420d2a2ea0d659682c06ac607572df55a43753aa12e", [:mix], [], "hexpm", "2ed2e25711feb44d52b17d2780eabf998452f6efda104877a3881c2f8c0c0c75"},
   "ex_check": {:hex, :ex_check, "0.14.0", "d6fbe0bcc51cf38fea276f5bc2af0c9ae0a2bb059f602f8de88709421dae4f0e", [:mix], [], "hexpm", "8a602e98c66e6a4be3a639321f1f545292042f290f91fa942a285888c6868af0"},
-  "ex_doc": {:hex, :ex_doc, "0.24.2", "e4c26603830c1a2286dae45f4412a4d1980e1e89dc779fcd0181ed1d5a05c8d9", [:mix], [{:earmark_parser, "~> 1.4.0", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "e134e1d9e821b8d9e4244687fb2ace58d479b67b282de5158333b0d57c6fb7da"},
+  "ex_doc": {:hex, :ex_doc, "0.25.3", "3edf6a0d70a39d2eafde030b8895501b1c93692effcbd21347296c18e47618ce", [:mix], [{:earmark_parser, "~> 1.4.0", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "9ebebc2169ec732a38e9e779fd0418c9189b3ca93f4a676c961be6c1527913f5"},
   "excoveralls": {:hex, :excoveralls, "0.14.1", "14140e4ef343f2af2de33d35268c77bc7983d7824cb945e6c2af54235bc2e61f", [:mix], [{:hackney, "~> 1.16", [hex: :hackney, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "4a588f9f8cf9dc140cc1f3d0ea4d849b2f76d5d8bee66b73c304bb3d3689c8b0"},
   "file_system": {:hex, :file_system, "0.2.10", "fb082005a9cd1711c05b5248710f8826b02d7d1784e7c3451f9c1231d4fc162d", [:mix], [], "hexpm", "41195edbfb562a593726eda3b3e8b103a309b733ad25f3d642ba49696bf715dc"},
   "hackney": {:hex, :hackney, "1.17.4", "99da4674592504d3fb0cfef0db84c3ba02b4508bae2dff8c0108baa0d6e0977c", [:rebar3], [{:certifi, "~>2.6.1", [hex: :certifi, repo: "hexpm", optional: false]}, {:idna, "~>6.1.0", [hex: :idna, repo: "hexpm", optional: false]}, {:metrics, "~>1.0.0", [hex: :metrics, repo: "hexpm", optional: false]}, {:mimerl, "~>1.1", [hex: :mimerl, repo: "hexpm", optional: false]}, {:parse_trans, "3.3.1", [hex: :parse_trans, repo: "hexpm", optional: false]}, {:ssl_verify_fun, "~>1.1.0", [hex: :ssl_verify_fun, repo: "hexpm", optional: false]}, {:unicode_util_compat, "~>0.7.0", [hex: :unicode_util_compat, repo: "hexpm", optional: false]}], "hexpm", "de16ff4996556c8548d512f4dbe22dd58a587bf3332e7fd362430a7ef3986b16"},

diff --git a/notebooks/expand_multi_alias.livemd b/notebooks/expand_multi_alias.livemd
@@ -27,7 +27,7 @@ end
 quoted = Sourceror.parse_string!(source)
 ```
 
-We need to traverse the ast to find any ocurrence of a qualified tuple call(ie.
+We need to traverse the ast to find any occurrence of a qualified tuple call(ie.
 calls with the form `{:., meta, [left, :{}]}` as their first element) that is an argument
 to an `:alias` call. Then for each module inside of the curly brackets, we need to join
 the module segments from the left hand side with the ones in the right hand side, and

diff --git a/notebooks/zippers.livemd b/notebooks/zippers.livemd
@@ -39,7 +39,7 @@ If we wanted to move to the right, we would perform the same operation, but popp
 and prepending to the left. Such movements are performed in constant time, making zippers an
 attractive option when a lot of movements over a list are required, but things start to get more
 interesting when we use zippers with trees. When moving across a list, we are constrained to
-horizonal movements(left and right), but in trees we have an extra dimension to move around(up and
+horizontal movements(left and right), but in trees we have an extra dimension to move around(up and
 down). So we need to encode at least four things: the focus, the left and right siblings, and the
 parent nodes in the tree.
 
@@ -121,7 +121,7 @@ other kinds of movements to traverse it. For zippers, we have `Z.next/1` and `Z.
 one step forward or backwards in depth-first pre-order, and `Z.traverse/2-3` to perform a depth-first
 pre-order traversal while calling a function at each location.
 
-To demonstrate the ability of zippers to look arount at the rest of the tree, we will traverse a tree
+To demonstrate the ability of zippers to look around at the rest of the tree, we will traverse a tree
 of lists and integers, multiplying each integer by the integer at it's right, or removing it if it's
 already the rightmost sibling, or the following element is another list:
 
@@ -148,5 +148,5 @@ the traversal ended, preventing subsequent calls to `Z.next/1` from going down t
 `Z.node/1` function just extracts the current node from the zipper, so we can look at the final result
 instead of a zipper.
 
-That wraps up the introduction to zippers. We'll see them in action in the "Multi alias exapansion"
-livebook, where we use them to simplify the traversal and tranformations.
+That wraps up the introduction to zippers. We'll see them in action in the "Multi alias expansion"
+livebook, where we use them to simplify the traversal and transformations.