From 8ceb1d11677b707b9de0c4eed9b5a7733ea2dd18 Mon Sep 17 00:00:00 2001 From: "Kian-Meng, Ang" Date: Tue, 2 Nov 2021 08:39:29 +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 | 5 +++-- .gitignore | 18 ++++++++++++------ README.md | 19 ++++++++++++++----- lib/mix/tasks/bin/db.ex | 2 +- lib/mix/tasks/version.ex | 4 ++-- lib/version_tasks.ex | 4 ++-- mix.exs | 21 +++++++++++++++------ mix.lock | 7 ++++--- 8 files changed, 53 insertions(+), 27 deletions(-) diff --git a/.formatter.exs b/.formatter.exs index 55d3bcc..d2cda26 100644 --- a/.formatter.exs +++ b/.formatter.exs @@ -1,3 +1,4 @@ +# Used by "mix format" [ - inputs: ["mix.exs", "{config,lib,test}/**/*.{ex,exs}"] -] \ No newline at end of file + inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"] +] diff --git a/.gitignore b/.gitignore index ef49bb6..f78dad2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,14 +1,14 @@ # The directory Mix will write compiled artifacts to. -/_build +/_build/ # If you run "mix test --cover", coverage assets end up here. -/cover +/cover/ # The directory Mix downloads your dependencies sources to. -/deps +/deps/ -# Where 3rd-party dependencies like ExDoc output generated docs. -/doc +# Where third-party dependencies like ExDoc output generated docs. +/doc/ # Ignore .fetch files in case you like to edit your project deps locally. /.fetch @@ -19,7 +19,13 @@ erl_crash.dump # Also ignore archive artifacts (built via "mix archive.build"). *.ez -# Code generated from task during testing +# Ignore package tarball (built via "mix hex.build"). +version_task-*.tar + +# Temporary files, for example, from tests. +/tmp/ + +# Code generated from task during testing. /bin /lib/version_tasks/release.ex rel/commands diff --git a/README.md b/README.md index 1be2658..ef19527 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,11 @@ # VersionTasks +[![Module Version](https://img.shields.io/hexpm/v/version_tasks.svg)](https://hex.pm/packages/version_tasks) +[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/version_tasks/) +[![Total Download](https://img.shields.io/hexpm/dt/version_tasks.svg)](https://hex.pm/packages/version_tasks) +[![License](https://img.shields.io/hexpm/l/version_tasks.svg)](https://github.com/aforward/version_tasks/blob/master/LICENSE.md) +[![Last Updated](https://img.shields.io/github/last-commit/aforward/version_tasks.svg)](https://github.com/aforward/version_tasks/commits/master) + Provides an opinionated, but rational, set of mix tools for managing version numbers for your Elixir project using the following scheme. @@ -8,7 +14,7 @@ Major.Minor.Patch ``` You decide what each version number means, whether it's [semantic -versionning](http://semver.org/), [Spec-ulation from Rich Hickey](https://www.youtube.com/watch?v=oyLBGkS5ICk), or any other scheme. +versioning](http://semver.org/), [Spec-ulation from Rich Hickey](https://www.youtube.com/watch?v=oyLBGkS5ICk), or any other scheme. ## Installation @@ -118,7 +124,7 @@ message, this delegates to git and simply calls (`git log --format=%B -n 1 HEAD` mix version.last_commit Simplify the database backup, to make restore easier - # Hey, this commmit looks like a new release was commit + # Hey, this commit looks like a new release was commit mix version.last_commit v1.4.5 @@ -126,7 +132,7 @@ message, this delegates to git and simply calls (`git log --format=%B -n 1 HEAD` #### mix version.(major|minor|patch) You can also expose just the major number, or minor number or patch number. -This would be useful for scriping where you wanted to join the numbers with +This would be useful for scripting where you wanted to join the numbers with a dash, and your `bash` is not up to the par, so you call it out individually. # Let's assume `mix version.current` is 1.2.3 @@ -377,9 +383,12 @@ The script will create the following files: You will need to commit these files to you project. If you edit them, please let me (aforward@gmail.com) as the changes might be relevant to others. -## License +## Copyright and License + +Copyright (c) 2017 Andrew Forward -MIT License +This work is free. You can redistribute it and/or modify it under the +terms of the MIT License. See the [LICENSE.md](./LICENSE.md) file for more details. ---- Created: 2017-07-05Z diff --git a/lib/mix/tasks/bin/db.ex b/lib/mix/tasks/bin/db.ex index 1156734..d70d735 100644 --- a/lib/mix/tasks/bin/db.ex +++ b/lib/mix/tasks/bin/db.ex @@ -10,7 +10,7 @@ defmodule Mix.Tasks.Version.Bin.Db do * `backup_root` -- Where to store backups * `dbname` -- The name of your database - Both arugments are optional and default to + Both arguments are optional and default to * `backup_root` -- /src/{appname}backup * `dbname` -- {appname} diff --git a/lib/mix/tasks/version.ex b/lib/mix/tasks/version.ex index a5f1f96..bf7beb1 100644 --- a/lib/mix/tasks/version.ex +++ b/lib/mix/tasks/version.ex @@ -6,7 +6,7 @@ defmodule Mix.Tasks.Version do @moduledoc """ version_tasks #{VersionTasks.version()} - version_tasks is a set of helper mix tasks to manange your projects version + version_tasks is a set of helper mix tasks to manage your projects version Available version tasks: @@ -50,7 +50,7 @@ defmodule Mix.Tasks.Version do @shortdoc "Learn more about the available version tasks" def run(_) do Shell.info("version_tasks v" <> VersionTasks.version()) - Shell.info("version_tasks is a set of helper mix tasks to manange your projects version") + Shell.info("version_tasks is a set of helper mix tasks to manage your projects version") Shell.newline() Shell.info("Available version tasks:") diff --git a/lib/version_tasks.ex b/lib/version_tasks.ex index d7d2479..469497a 100644 --- a/lib/version_tasks.ex +++ b/lib/version_tasks.ex @@ -99,14 +99,14 @@ defmodule VersionTasks do mix version.last_commit Simplify the database backup, to make restore easier - # Hey, this commmit looks like a new release was commit + # Hey, this commit looks like a new release was commit mix version.last_commit v1.4.5 ### mix version.(major|minor|patch) You can also expose just the major number, or minor number or patch number. - This would be useful for scriping where you wanted to join the numbers with + This would be useful for scripting where you wanted to join the numbers with a dash, and your `bash` is not up to the par, so you call it out individually. # Let's assume `mix version.current` is 1.2.3 diff --git a/mix.exs b/mix.exs index 0444a1d..fe57954 100644 --- a/mix.exs +++ b/mix.exs @@ -14,12 +14,24 @@ defmodule VersionTasks.Mixfile do @package [ name: @app, + description: "A suite of mix tasks for managing your libs version numbers with git and hex", files: ["lib", "mix.exs", "README*", "README*", "LICENSE*"], maintainers: ["Andrew Forward"], licenses: ["MIT"], links: %{"GitHub" => @git_url} ] + @docs [ + extras: [ + "README.md": [title: "Overview"] + ], + main: "readme", + homepage_url: @home_url, + source_url: @git_url, + source_ref: "v#{@version}", + formatters: ["html"] + ] + # ------------------------------------------------------------ def project do @@ -30,14 +42,11 @@ defmodule VersionTasks.Mixfile do version: @version, elixir: "~> 1.11", name: "VersionTasks", - description: "A suite of mix tasks for managing your libs version numbers with git and hex", - package: @package, - source_url: @git_url, - homepage_url: @home_url, - docs: [main: "VersionTasks", extras: ["README.md"]], build_embedded: in_production, start_permanent: in_production, - deps: @deps + package: @package, + deps: @deps, + docs: @docs ] end diff --git a/mix.lock b/mix.lock index 7e2f56c..c38d3fc 100644 --- a/mix.lock +++ b/mix.lock @@ -1,13 +1,14 @@ %{ "earmark": {:hex, :earmark, "1.4.4", "4821b8d05cda507189d51f2caeef370cf1e18ca5d7dfb7d31e9cafe6688106a4", [:mix], [], "hexpm", "1f93aba7340574847c0f609da787f0d79efcab51b044bb6e242cae5aca9d264d"}, - "earmark_parser": {:hex, :earmark_parser, "1.4.12", "b245e875ec0a311a342320da0551da407d9d2b65d98f7a9597ae078615af3449", [:mix], [], "hexpm", "711e2cc4d64abb7d566d43f54b78f7dc129308a63bc103fbd88550d2174b3160"}, - "ex_doc": {:hex, :ex_doc, "0.23.0", "a069bc9b0bf8efe323ecde8c0d62afc13d308b1fa3d228b65bca5cf8703a529d", [:mix], [{:earmark_parser, "~> 1.4.0", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm", "f5e2c4702468b2fd11b10d39416ddadd2fcdd173ba2a0285ebd92c39827a5a16"}, + "earmark_parser": {:hex, :earmark_parser, "1.4.17", "6f3c7e94170377ba45241d394389e800fb15adc5de51d0a3cd52ae766aafd63f", [:mix], [], "hexpm", "f93ac89c9feca61c165b264b5837bf82344d13bebc634cd575cb711e2e342023"}, + "ex_doc": {:hex, :ex_doc, "0.25.5", "ac3c5425a80b4b7c4dfecdf51fa9c23a44877124dd8ca34ee45ff608b1c6deb9", [: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", "688cfa538cdc146bc4291607764a7f1fcfa4cce8009ecd62de03b27197528350"}, "file_system": {:hex, :file_system, "0.2.10", "fb082005a9cd1711c05b5248710f8826b02d7d1784e7c3451f9c1231d4fc162d", [:mix], [], "hexpm", "41195edbfb562a593726eda3b3e8b103a309b733ad25f3d642ba49696bf715dc"}, "fn_expr": {:hex, :fn_expr, "0.1.0", "ef482fa3b355067f78cf7eadb82ea90f29b5d64a21d7d3e3e4a0eefdf4f71b4d", [], [], "hexpm"}, "fs": {:hex, :fs, "0.9.2", "ed17036c26c3f70ac49781ed9220a50c36775c6ca2cf8182d123b6566e49ec59", [:rebar], [], "hexpm"}, "git_cli": {:hex, :git_cli, "0.3.0", "a5422f9b95c99483385b976f5d43f7e8233283a47cda13533d7c16131cb14df5", [:mix], [], "hexpm", "78cb952f4c86a41f4d3511f1d3ecb28edb268e3a7df278de2faa1bd4672eaf9b"}, "makeup": {:hex, :makeup, "1.0.5", "d5a830bc42c9800ce07dd97fa94669dfb93d3bf5fcf6ea7a0c67b2e0e4a7f26c", [:mix], [{:nimble_parsec, "~> 0.5 or ~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cfa158c02d3f5c0c665d0af11512fed3fba0144cf1aadee0f2ce17747fba2ca9"}, - "makeup_elixir": {:hex, :makeup_elixir, "0.15.0", "98312c9f0d3730fde4049985a1105da5155bfe5c11e47bdc7406d88e01e4219b", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.1", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "75ffa34ab1056b7e24844c90bfc62aaf6f3a37a15faa76b07bc5eba27e4a8b4a"}, + "makeup_elixir": {:hex, :makeup_elixir, "0.15.2", "dc72dfe17eb240552857465cc00cce390960d9a0c055c4ccd38b70629227e97c", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.1", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "fd23ae48d09b32eff49d4ced2b43c9f086d402ee4fd4fcb2d7fad97fa8823e75"}, + "makeup_erlang": {:hex, :makeup_erlang, "0.1.1", "3fcb7f09eb9d98dc4d208f49cc955a34218fc41ff6b84df7c75b3e6e533cc65f", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "174d0809e98a4ef0b3309256cbf97101c6ec01c4ab0b23e926a9e17df2077cbb"}, "mix_test_watch": {:hex, :mix_test_watch, "0.9.0", "c72132a6071261893518fa08e121e911c9358713f62794a90c95db59042af375", [:mix], [{:file_system, "~> 0.2.1 or ~> 0.3", [hex: :file_system, repo: "hexpm", optional: false]}], "hexpm", "817dec4a7f6edf260258002f99ac8ffaf7a8f395b27bf2d13ec24018beecec8a"}, "nimble_parsec": {:hex, :nimble_parsec, "1.1.0", "3a6fca1550363552e54c216debb6a9e95bd8d32348938e13de5eda962c0d7f89", [:mix], [], "hexpm", "08eb32d66b706e913ff748f11694b17981c0b04a33ef470e33e11b3d3ac8f54b"}, "porcelain": {:hex, :porcelain, "2.0.3", "2d77b17d1f21fed875b8c5ecba72a01533db2013bd2e5e62c6d286c029150fdc", [:mix], [], "hexpm"},