Merge pull request #21 from zhongwencool/document

docs: user ex_doc to generate document

Author: zhongwencool

LICENSE

@@ -175,7 +175,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2019, zhongwencool <zhongwencool@gmail.com>.
+   Copyright 2019-2025, zhongwencool <zhongwencool@gmail.com>.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,46 +1,38 @@
-<!-- markdownlint-disable MD013 -->
-# ecron [![GitHub Actions][action-img]][action] [![codeCov-img]][codeCov] [![hex-img]][hex] [![tag]][tag] [![License]][License]
-[action]: https://github.com/zhongwencool/ecron
-[action-img]: https://github.com/zhongwencool/ecron/actions/workflows/ci.yml/badge.svg
-[codeCov]: https://codecov.io/gh/zhongwencool/ecron
-[codeCov-img]: https://codecov.io/gh/zhongwencool/ecron/branch/master/graph/badge.svg?token=FI9WAQ6UG5
-[hex]: https://hex.pm/packages/ecron
-[hex-img]: https://img.shields.io/hexpm/v/ecron.svg?style=flat
-[tag]: https://img.shields.io/github/tag/zhongwencool/ecron.svg
-[License]: https://img.shields.io/hexpm/l/ecron.svg
+# ecron [![GitHub Actions](https://github.com/zhongwencool/ecron/actions/workflows/ci.yml/badge.svg)](https://github.com/zhongwencool/ecron) [![CodeCov](https://codecov.io/gh/zhongwencool/ecron/branch/master/graph/badge.svg?token=FI9WAQ6UG5)](https://codecov.io/gh/zhongwencool/ecron) [![Hex](https://img.shields.io/hexpm/v/ecron.svg?style=flat)](https://hex.pm/packages/ecron) [![Tag](https://img.shields.io/github/tag/zhongwencool/ecron.svg)](https://img.shields.io/github/tag/zhongwencool/ecron.svg) [![License](https://img.shields.io/hexpm/l/ecron.svg)](https://img.shields.io/hexpm/l/ecron.svg) [![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/ecron/)
 
 A lightweight and efficient cron-like job scheduling library for Erlang.
 
-## Overview
+# Overview
 Ecron is designed to manage scheduled jobs within a single gen_server process, similar to the standard library's [stdlib's timer](http://erlang.org/doc/man/timer.html). It uses an ordered_set ETS table to organize jobs by the next run time, ensuring efficient execution. Unlike traditional cron, Ecoron does not poll the system every second, which reduces message overhead and process usage.
 
-more detail see [Implementation](#Implementation).
+## Key Features
 
-
-### Key Features
 - Supports both cron-like and interval-based scheduling.
 - Well-tested with [PropTest](https://github.com/proper-testing/proper) [![codecov](https://codecov.io/gh/zhongwencool/ecron/branch/master/graph/badge.svg?token=FI9WAQ6UG5)](https://codecov.io/gh/zhongwencool/ecron).
 - Utilizes gen_server timeout mechanism for precise timing.
 - Efficient process management, avoiding high memory usage.
 
-You can find a collection of general practices in [Full Erlang Examples](https://github.com/zhongwencool/ecron/blob/master/examples/titan_erlang) and [Full Elixir Examples](https://github.com/zhongwencool/ecron/blob/master/examples/titan_elixir).
-
 ## Installation
-  
-**Erlang**
- ```erlang
+
+<!-- tabs-open -->
+
+### Erlang
+
+```erlang
   %% rebar.config
   {deps, [ecron]}
- ```
+```
+### Elixir
 
-**Elixir**
- ```elixir
+```elixir
   # mix.exs
   def deps do
     [{:ecron, "~> 1.0.1"}]
   end
 ```
 
+<!-- tabs-close -->
+
 ## Basic Usage 
 
 Configure Ecoron in your sys.config file with timezone and job specifications:
@@ -146,6 +138,9 @@ ok = ecron:delete(crontabuniqueName),
 EveryMFA = {io, format, ["Runs every 120 second.~n"]},
 {ok, _} = ecron:add(everyUniqueName, 120, EveryMFA),
 ```
+
+You can find a collection of general practices in [Full Erlang Examples](https://github.com/zhongwencool/ecron/blob/master/examples/titan_erlang) and [Full Elixir Examples](https://github.com/zhongwencool/ecron/blob/master/examples/titan_elixir).
+
 ## Debug Support
 
 Ecron provides functions to assist with debugging:
@@ -225,97 +220,98 @@ Additionally, you can use `ecron:statistic(Name)` to see the job's latest 16 res
              |<-------|
 ```
 
-[Check this for global_jobs workflow](https://github.com/zhongwencool/ecron/blob/master/doc/global.md#Implementation).       
+[Check this for global_jobs workflow](global.html#Implementation).       
 
-## Telemetry
+## CRON Expression Guide
 
-Ecron publishes events through telemetry, allowing for monitoring and alerting,
-You can handle those events by [this guide](https://github.com/zhongwencool/ecron/blob/master/doc/telemetry.md).
+### Basic Format
 
-## CRON Expression Format
+A cron expression consists of 5-6 fields representing time units:
 
-A [cron expression](https://www.wikiwand.com/en/Cron) represents a set of times, using 5-6 space-separated fields.
-Currently, W (nearest weekday), L (last day of month/week), and # (nth weekday of the month) are not supported. 
-
-Most other features supported by popular cron implementations should work just fine.
-```shell script
- # ┌────────────── second (optional)
- # │ ┌──────────── minute
- # │ │ ┌────────── hour
- # │ │ │ ┌──────── day of month
- # │ │ │ │ ┌────── month
- # │ │ │ │ │ ┌──── day of week
- # │ │ │ │ │ │
- # │ │ │ │ │ │
- # 0 * * * * *
+```
+# ┌────────────── second (optional)
+# │ ┌──────────── minute
+# │ │ ┌────────── hour
+# │ │ │ ┌──────── day of month
+# │ │ │ │ ┌────── month
+# │ │ │ │ │ ┌──── day of week
+# │ │ │ │ │ │
+# │ │ │ │ │ │
+# 0 * * * * *
 ```
 
-Field name   | Mandatory? | Allowed values  | Allowed special characters
-----------   | ---------- | --------------  | --------------------------
-Seconds      | No         | 0-59            | * / , -
-Minutes      | Yes        | 0-59            | * / , -
-Hours        | Yes        | 0-23            | * / , -
-Day of month | Yes        | 1-31            | * / , -
-Month        | Yes        | 1-12 or JAN-DEC | * / , -
-Day of week  | Yes        | 0-6 or SUN-SAT  | * / , -
+### Field Values
 
-Note: Month and Day-of-week field values are case-insensitive. "SUN", "Sun", and "sun" are equally accepted.
+Field | Required | Values | Special Characters
+Second | No | 0-59 | `* / , -`
+Minute | Yes | 0-59 | `* / , -`
+Hour | Yes | 0-23 | `* / , -`
+Day of Month | Yes | 1-31 | `* / , -`
+Month | Yes | 1-12 or JAN-DEC | `* / , -`
+Day of Week | Yes | 0-6 or SUN-SAT | `* / , -`
 
-When specifying your cron values you'll need to make sure that your values fall within the ranges. 
-For instance, some cron's use a 0-7 range for the day of week where both 0 and 7 represent Sunday. We do not.
+> **Note**: Month and Day-of-week values are case-insensitive.
 
 ### Special Characters
-#### Asterisk ( * )
-The asterisk indicates that the cron expression will match for all values of the field. 
-For example, using an asterisk in the `month` field would indicate every month.
 
-#### Slash ( / )
-Slashes are used to describe increments of ranges. 
-For example, "3-59/15" in the `minutes` field would indicate the 3rd minute of the hour and every 15 minutes thereafter. 
-The form "*/..." is equivalent to the form "First-Last/...", that is, an increment over the largest possible range of the field. 
-The form "N/..." is accepted as meaning "N-Max/...", that is, starting at N, use the increment until the end of that specific range. 
-It does not wrap around.
+- `*` - Any value
+- `/` - Step values (e.g., `*/15` - every 15 units)
+- `,` - Value list (e.g., `1,3,5`)
+- `-` - Range (e.g., `1-5`)
 
-#### Comma ( , )
-Commas are used to separate items of a list. 
-For example, using "MON,WED,FRI" in the `day_of_week` field would mean Mondays, Wednesdays and Fridays.
+### Predefined Schedules
 
-#### Hyphen ( - )
-Hyphens are used to define ranges. 
-For example, using "9-17" in the `hours`field  would indicate every hour between 9am and 5pm inclusive.
+Expression | Description | Equivalent
+`@yearly` | Once a year (midnight, Jan 1) | `0 0 0 1 1 *`
+`@monthly` | Once a month (midnight, first day) | `0 0 0 1 * *`
+`@weekly` | Once a week (midnight, Sunday) | `0 0 0 * * 0`
+`@daily` | Once a day (midnight) | `0 0 0 * * *`
+`@hourly` | Once an hour | `0 0 * * * *`
+`@minutely` | Once a minute | `0 * * * * *`
 
-## Predefined crontab
+### Fixed Intervals
 
-You may use one of several pre-defined crontab in place of a cron expression.
+For simpler scheduling needs, use `@every` with a duration:
 
-Entry                  | Description                                | Equivalent To
------                  | -----------                                | -------------
-@yearly (or @annually) | Run once a year, midnight, Jan. 1st        | 0 0 0 1 1 *
-@monthly               | Run once a month, midnight, first of month | 0 0 0 1 * *
-@weekly                | Run once a week, midnight between Sat/Sun  | 0 0 0 * * 0
-@daily (or @midnight)  | Run once a day, midnight                   | 0 0 0 * * *
-@hourly                | Run once an hour, beginning of hour        | 0 0 * * * *
-@minutely              | Run once an minute, beginning of minute    | 0 * * * * *
+```erlang
+% Run every 30 minutes
+"@every 30m"
 
->There are tools that help when constructing your cronjobs. 
->You might find something like [https://crontab.guru/](https://crontab.guru/) or [https://cronjob.xyz/](https://cronjob.xyz/) helpful. 
->But, note that these don't necessarily accept the exact same syntax as this library, 
->for instance, it doesn't accept the seconds field, so keep that in mind.
->The best way to verify the spec format is `ecron:parse_spec("0 0 1 1 1-6 1", 10).`. 
+% Run every 1 hour and 30 minutes
+"@every 1h30m"
+```
 
-## Intervals
+Duration units: `d`(days), `h`(hours), `m`(minutes), `s`(seconds)
 
-Ecron also supports scheduling jobs at fixed intervals:
+### Error Handling
 
-```shell
-@every <duration>
-```
-For example, @every 1h30m10s schedules a job to run every 1 hour, 30 minutes, and 10 seconds.
+- Failed jobs don't affect other jobs
+- Execution results and timing are stored (last 16 runs)
+- Jobs can be configured as singleton or parallel
+- System time changes are handled gracefully
+
+## Best Practices
+
+1. **Job Names**
+   - Use descriptive, unique names
+   - Consider adding prefixes for different job types
+
+2. **Time Windows**
+   - Use start/end times for temporary jobs
+   - Consider time zone implications
+
+3. **Error Handling**
+   - Implement proper error handling in job functions
+   - Monitor job execution through telemetry
+
+4. **Resource Management**
+   - Group related jobs under same supervisor
+   - Use `singleton: false` only when needed
+
+5. **Testing**
+   - Validate cron expressions before deployment
+   - Test jobs with different time scenarios
 
->Note: The interval doesn't take the job runtime into account. 
->For example, if a job takes 3 minutes to run, and it is scheduled to run every 5 minutes, 
->it only has 2 minutes of idle time between each run.
-  
 ## Test
 
 This command will run property-based tests, common tests, and generate a coverage report with verbose output.

changelog.md

@@ -1,3 +1,13 @@
+
+### 1.0.2
+- Use ex_doc to update documentation.
+
+### 1.0.1
+- Fix concurrent cron job execution timing issue.
+
+### 1.0.0
+Nothing changed, just update version from 0.6.1 to 1.0.0.
+
 ### 0.6.1
 - fix some spec warning.
 - upgrade telemetry to 1.1.0

doc/global.md global.mddoc/global.md renamed to global.md

@@ -5,7 +5,7 @@
 
 {profiles, [{test, [{deps, [proper]}]}]}.
 {project_plugins, [
-    rebar3_proper, covertool, {rebar3_edoc_extensions, "1.5.0"}, rebar3_format, erlfmt
+    rebar3_proper, covertool, rebar3_ex_doc, rebar3_format, erlfmt
 ]}.
 
 {cover_enabled, true}.
@@ -24,15 +24,6 @@
     deprecated_functions
 ]}.
 
-{edoc_opts, [
-    {stylesheet, "stylesheet.css"},
-    {preprocess, true},
-    {includes, ["."]},
-    {sort_functions, false},
-    {doclet, edoc_doclet_chunks},
-    {layout, edoc_layout_chunks}
-]}.
-
 {alias, [
     {check, [
         xref,
@@ -55,3 +46,23 @@
     %% ...or no options at all.
     {options, #{print_width => 120, ignore_pragma => true}}
 ]}.
+
+{hex, [
+    {doc, #{provider => ex_doc}}
+]}.
+
+{ex_doc, [
+    {extras, [
+        {"README.md", #{title => "Overview"}},
+
+        {"telemetry.md", #{title => "Telemetry"}},
+        {"global.md", #{title => "Cluster Task"}},
+        {"CHANGELOG.md", #{title => "Changelog"}},
+        {"LICENSE", #{title => "License"}}
+    ]},
+    {main, "README.md"},
+    {homepage_url, "https://github.com/zhongwencool/ecron"},
+    {source_url, "https://github.com/zhongwencool/ecron"},
+    {api_reference, false},
+    {with_mermaid, true}
+]}.

rebar.config

@@ -1,6 +1,6 @@
 {application, ecron, [
     {description, "cron-like/crontab job scheduling library"},
-    {vsn, "1.0.1"},
+    {vsn, "1.0.2"},
     {registered, [ecron_sup, ecron_local, ecron_monitor]},
     {mod, {ecron_app, []}},
     {applications, [kernel, stdlib, telemetry]},
@@ -31,6 +31,6 @@
         ]}
     ]},
     {modules, []},
-    {licenses, ["Apache 2.0"]},
+    {licenses, ["Apache-2.0"]},
     {links, [{"Github", "https://github.com/zhongwencool/ecron"}]}
 ]}.