Misc doc changes (#26)

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.
toggl · Apr 2, 2024 · 6372c57 · 6372c57
1 parent 4271c4f
commit 6372c57
Show file tree

Hide file tree

Showing 15 changed files with 61 additions and 49 deletions.
diff --git a/.formatter.exs b/.formatter.exs
@@ -1,3 +1,4 @@
+# Used by "mix format"
 [
-  inputs: ["mix.exs", "{config,lib,test}/**/*.{ex,exs}"]
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
 ]
diff --git a/.gitignore b/.gitignore
@@ -8,12 +8,8 @@
 # The directory Mix downloads your dependencies sources to.
 /deps/
 
-# Where 3rd-party dependencies like ExDoc output generated docs.
+# Where third-party dependencies like ExDoc output generated docs.
 /doc/
-/docs/
-
-# Temp files
-/tmp/
 
 # Ignore .fetch files in case you like to edit your project deps locally.
 /.fetch
@@ -24,6 +20,13 @@ erl_crash.dump
 # Also ignore archive artifacts (built via "mix archive.build").
 *.ez
 
+# Ignore package tarball (built via "mix hex.build").
+holidefs-*.tar
+
+# Temporary files, for example, from tests.
+/tmp/
+
+# Misc.
 .DS_Store
 
 ### nix ###

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # Changelog
 
+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.3.8 - 2023-09-25
 
 ### Changed
@@ -96,4 +101,3 @@ https://github.com/holidays/definitions/tree/v2.3.0 tag
 - README usage section
 - Loading and handling of holiday definition files from http://github.com/holidays/definitions
 - Informal and observed options
-
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -12,7 +12,7 @@ Here is a step by step for contributing to the project:
 - Open a PR
 - Wait for review!
 
-## Releasing
+### Releasing
 
 Here is the step by step to release the project (team members only):
 
@@ -21,9 +21,9 @@ Here is the step by step to release the project (team members only):
 - Make sure CI passes and docs are good
 - Prepare the version branch:
   - If you're releasing a major or minor, open a branch for it, with a naming like `1.0`
-  - If you're releasing a patch with all the things on master, checkout the minor branch and 
+  - If you're releasing a patch with all the things on master, checkout the minor branch and
   `git rebase master` on it
-  - If you're releasing a patch, but can't get everything of master, `git cherry-pick <sha>` of 
+  - If you're releasing a patch, but can't get everything of master, `git cherry-pick <sha>` of
   every commit you need and push it
 - Create a draft for your release on Github
   - From branch: `1.0`

diff --git a/LICENSE → LICENSE.md b/LICENSE → LICENSE.md
@@ -1,4 +1,4 @@
-MIT License
+# MIT License
 
 Copyright (c) 2018 Teamweek
 

diff --git a/README.md b/README.md
@@ -1,11 +1,11 @@
 # Holidefs
 
-[![Build Status](https://travis-ci.org/Teamweek/holidefs.svg?branch=master)](https://travis-ci.org/Teamweek/holidefs)
+[![CI](https://github.com/toggl/holidefs/actions/workflows/elixir.yml/badge.svg)](https://github.com/toggl/holidefs/actions/workflows/elixir.yml)
 [![Module Version](https://img.shields.io/hexpm/v/holidefs.svg)](https://hex.pm/packages/holidefs)
 [![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/holidefs/)
 [![Total Download](https://img.shields.io/hexpm/dt/holidefs.svg)](https://hex.pm/packages/holidefs)
-[![License](https://img.shields.io/hexpm/l/holidefs.svg)](https://github.com/Teamweek/holidefs/blob/master/LICENSE)
-[![Last Updated](https://img.shields.io/github/last-commit/Teamweek/holidefs.svg)](https://github.com/Teamweek/holidefs/commits/master)
+[![License](https://img.shields.io/hexpm/l/holidefs.svg)](https://github.com/toggl/holidefs/blob/master/LICENSE.md)
+[![Last Updated](https://img.shields.io/github/last-commit/toggl/holidefs.svg)](https://github.com/toggl/holidefs/commits/master)
 
 Definition-based national holidays in Elixir.
 
@@ -46,8 +46,8 @@ Holidefs.between(:br, ~D[2018-02-01], ~D[2018-04-03], include_informal?: true)
 For the complete list of options and their meaning check
 [`Holidefs.Options` doc](http://hexdocs.pm/holidefs/Holidefs.Options.html)
 
-## Copyright and License
+## License
 
 Copyright (c) 2022 Toggl
 
-This software is released under the [MIT License](./LICENSE).
+This software is released under the [MIT License](./LICENSE.md).
diff --git a/config/config.exs b/config/config.exs
@@ -21,4 +21,4 @@ use Mix.Config
 #     config :logger, level: :info
 #
 
-import_config "#{Mix.env}.exs"
+import_config "#{Mix.env()}.exs"
diff --git a/dev/support/mix/tasks/holidefs.download.ex b/dev/support/mix/tasks/holidefs.download.ex
@@ -3,21 +3,22 @@ defmodule Mix.Tasks.Holidefs.Download do
 
   alias Holidefs.Definition
 
-  @shortdoc "Downloads the .yaml files with the calendar definitions"
+  @shortdoc "Downloads the .yaml files with the calendar definitions."
 
   @moduledoc """
   Downloads the definition files from https://github.com/holidays/definitions.
 
-  ## Example
+  ## Examples
 
-    mix holidefs.download
+      mix holidefs.download
 
   ## Command line options
 
     * `-l`, `--locale` - the locale code (or list of locale codes separated
-    by comma). All locales by default
+      by comma). All locales by default
+
     * `-c`, `--clean` - removes all locale files that are not needed anymore
-    before processing the list
+      before processing the list
 
   """
 

diff --git a/dev/support/mix/tasks/holidefs.gettext.extract.ex b/dev/support/mix/tasks/holidefs.gettext.extract.ex
@@ -4,7 +4,7 @@ defmodule Mix.Tasks.Holidefs.Gettext.Extract do
   alias Holidefs.Definition
   alias Holidefs.Definition.Store
 
-  @shortdoc "Extracts a new .pot from the definition files"
+  @shortdoc "Extracts a new .pot from the definition files."
 
   @moduledoc """
   Extracts a new .pot from all the definition files we load
@@ -14,9 +14,9 @@ defmodule Mix.Tasks.Holidefs.Gettext.Extract do
   or add new translations to the existing ones. Execute the command
   `mix help gettext.merge` to check how.
 
-  ## Example
+  ## Examples
 
-    mix holidefs.gettext.extract
+      mix holidefs.gettext.extract
 
   """
 

diff --git a/lib/holidefs/date_calculator.ex b/lib/holidefs/date_calculator.ex
@@ -1,10 +1,10 @@
 defmodule Holidefs.DateCalculator do
   @moduledoc """
-  Some functions to calculate dynamic holiday dates
+  Some functions to calculate dynamic holiday dates.
   """
 
   @doc """
-  Returns the date of Easter for the given `year`
+  Returns the date of Easter for the given `year`.
 
   ## Examples
 
@@ -39,7 +39,7 @@ defmodule Holidefs.DateCalculator do
   end
 
   @doc """
-  Returns the date of Orthodox Easter for the given `year`
+  Returns the date of Orthodox Easter for the given `year`.
 
   ## Examples
 
@@ -75,7 +75,7 @@ defmodule Holidefs.DateCalculator do
   end
 
   @doc """
-  Returns the date of Orthodox Easter for the given `year`
+  Returns the date of Orthodox Easter for the given `year`.
 
   ## Examples
 
@@ -100,7 +100,7 @@ defmodule Holidefs.DateCalculator do
   end
 
   @doc """
-  Returns the nth day of the week
+  Returns the nth day of the week.
   """
   @spec nth_day_of_week(integer, integer, integer, integer) :: Date.t()
   def nth_day_of_week(year, month, -1, weekday) do
@@ -128,7 +128,7 @@ defmodule Holidefs.DateCalculator do
   end
 
   @doc """
-  Returns the next day of week after the given day
+  Returns the next day of week after the given day.
   """
   @spec next_day_of_week(Date.t(), integer) :: Date.t()
   def next_day_of_week(date, day_of_week) do
@@ -142,7 +142,7 @@ defmodule Holidefs.DateCalculator do
   end
 
   @doc """
-  Returns the previous day of week after the given day
+  Returns the previous day of week after the given day.
   """
   @spec previous_day_of_week(Date.t(), integer) :: Date.t()
   def previous_day_of_week(date, day_of_week) do
@@ -156,7 +156,7 @@ defmodule Holidefs.DateCalculator do
   end
 
   @doc """
-  Returns the first day of the given month on the given year
+  Returns the first day of the given month on the given year.
   """
   @spec beginning_of_month(integer, integer) :: Date.t()
   def beginning_of_month(year, month) do

diff --git a/lib/holidefs/definition.ex b/lib/holidefs/definition.ex
@@ -16,13 +16,13 @@ defmodule Holidefs.Definition do
         }
 
   @doc """
-  Returns the path for the given locale definition file
+  Returns the path for the given locale definition file.
   """
   @spec file_path(atom, Path.t()) :: binary
   def file_path(code, path \\ path()), do: Path.join(path, "#{code}.yaml")
 
   @doc """
-  Returns the path where all the locale definitions are saved
+  Returns the path where all the locale definitions are saved.
   """
   @spec path() :: Path.t()
   def path() do

diff --git a/lib/holidefs/definition/store.ex b/lib/holidefs/definition/store.ex
@@ -8,13 +8,13 @@ defmodule Holidefs.Definition.Store do
   definitions = for {c, n} <- Holidefs.locales(), do: Definition.load!(c, n)
 
   @doc """
-  Returns all the loaded definitions with their rules
+  Returns all the loaded definitions with their rules.
   """
   @spec all_definitions :: [Holidefs.Definition.t()]
   def all_definitions, do: unquote(Macro.escape(definitions))
 
   @doc """
-  Returns the definitions for the given locale
+  Returns the definitions for the given locale.
   """
   @spec get_definition(Holidefs.locale_code()) :: Holidefs.Definition.t() | nil
   for definition <- definitions do

diff --git a/lib/holidefs/holiday.ex b/lib/holidefs/holiday.ex
@@ -21,7 +21,7 @@ defmodule Holidefs.Holiday do
         }
 
   @doc """
-  Returns a list of holidays for the definition rule on the given year
+  Returns a list of holidays for the definition rule on the given year.
   """
   @spec from_rule(atom, Holidefs.Definition.Rule.t(), integer, Holidefs.Options.t()) :: [t]
   def from_rule(code, %Rule{year_ranges: year_ranges} = rule, year, opts \\ %Options{}) do
@@ -133,7 +133,7 @@ defmodule Holidefs.Holiday do
   end
 
   @doc """
-  Returns the translated name of the given holiday
+  Returns the translated name of the given holiday.
   """
   @spec translate_name(atom, String.t()) :: String.t()
   def translate_name(code, name) do

diff --git a/lib/holidefs/options.ex b/lib/holidefs/options.ex
@@ -2,13 +2,15 @@ defmodule Holidefs.Options do
   @moduledoc """
   Here is the list of options you can send to `Holidefs` functions:
 
-    * `regions` - a list of strings to define what region will be loaded. When
-    empty it fallbacks to the basic region of the locale, which is the region
-    with the same code of the locale. Defaults to `[]`
-    * `include_informal?` - flag to include the informal holidays on the
-    return list. Defaults to `false`
-    * `observed?` - flag to consider the `observed_date` of the holidays as
-    the `date`. Defaults to `false`
+    * `:regions` - a list of strings to define what region will be loaded. When
+      empty it fallbacks to the basic region of the locale, which is the region
+      with the same code of the locale. Defaults to `[]`
+
+    * `:include_informal?` - flag to include the informal holidays on the
+      return list. Defaults to `false`
+
+    * `:observed?` - flag to consider the `observed_date` of the holidays as
+      the `date`. Defaults to `false`
 
   """
 

diff --git a/mix.exs b/mix.exs
@@ -1,7 +1,7 @@
 defmodule Holidefs.Mixfile do
   use Mix.Project
 
-  @github_url "https://github.com/Teamweek/holidefs"
+  @github_url "https://github.com/toggl/holidefs"
   @version "0.3.8"
 
   def project do
@@ -46,14 +46,15 @@ defmodule Holidefs.Mixfile do
         "CHANGELOG.md": [],
         "CODE_OF_CONDUCT.md": [title: "Code of Conduct"],
         "CONTRIBUTING.md": [],
-        LICENSE: [title: "License"],
+        "LICENSE.md": [title: "License"],
         "README.md": [title: "Overview"]
       ],
       main: "readme",
       source_url: @github_url,
       source_ref: "#v{@version}",
       homepage_url: @github_url,
-      formatters: ["html"]
+      formatters: ["html"],
+      api_reference: false
     ]
   end