From 555e56ead76eab1d53fe4817ccc8d512e1f84e27 Mon Sep 17 00:00:00 2001 From: "Kian-Meng, Ang" Date: Thu, 22 Jul 2021 21:25:44 +0800 Subject: [PATCH] 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. --- .formatter.exs | 3 ++- .gitignore | 13 ++++++++----- CHANGELOG.md | 6 +++++- CONTRIBUTING.md | 6 +++--- LICENSE => LICENSE.md | 2 +- README.md | 10 +++++----- config/config.exs | 2 +- dev/support/mix/tasks/holidefs.download.ex | 11 ++++++----- .../mix/tasks/holidefs.gettext.extract.ex | 6 +++--- lib/holidefs/date_calculator.ex | 16 ++++++++-------- lib/holidefs/definition.ex | 4 ++-- lib/holidefs/definition/store.ex | 4 ++-- lib/holidefs/holiday.ex | 4 ++-- lib/holidefs/options.ex | 16 +++++++++------- mix.exs | 7 ++++--- 15 files changed, 61 insertions(+), 49 deletions(-) rename LICENSE => LICENSE.md (98%) diff --git a/.formatter.exs b/.formatter.exs index 2bed17c..d2cda26 100644 --- 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 index 2f7551c..ae6b04a 100644 --- 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 index 1c88b54..a088464 100644 --- 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 index d2ce51c..b005566 100644 --- 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 ` of + - If you're releasing a patch, but can't get everything of master, `git cherry-pick ` of every commit you need and push it - Create a draft for your release on Github - From branch: `1.0` diff --git a/LICENSE b/LICENSE.md similarity index 98% rename from LICENSE rename to LICENSE.md index 0c0df8f..11014ab 100644 --- a/LICENSE +++ b/LICENSE.md @@ -1,4 +1,4 @@ -MIT License +# MIT License Copyright (c) 2018 Teamweek diff --git a/README.md b/README.md index aa25815..e5e362e 100644 --- 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 index 947adec..78a3759 100644 --- 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 index f78b1fa..5eda84e 100644 --- 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 index 154628b..9f38dd2 100644 --- 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 index cafaec7..c09c300 100644 --- 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 index 81227ec..61319ad 100644 --- 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 index 943ba9b..83d912f 100644 --- 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 index db903a2..f474919 100644 --- 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 index 9f7a2c1..0542e21 100644 --- 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 index 696614a..090e5d9 100644 --- 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 @@ -47,14 +47,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