chore(docs): auto generate docs

epwalsh · Dec 2, 2023 · df4c253 · df4c253
1 parent 153c3cc
commit df4c253
Showing 1 changed file with 33 additions and 15 deletions.
diff --git a/doc/pomo.txt b/doc/pomo.txt
@@ -3,12 +3,21 @@
 pomo.nvim
 
 A simple, customizable pomodoro
-<https://en.wikipedia.org/wiki/Pomodoro_Technique> timer for Neovim, written in
-Lua.
+<https://en.wikipedia.org/wiki/Pomodoro_Technique> timer plugin for Neovim,
+written in Lua.
 
 
 <https://github.com/epwalsh/pomo.nvim/assets/8812459/37e58af1-c8d3-470e-b63f-35b22cd308af>
 
+In **pomo.nvim**, most of the functionality is surfaced through the `Notifier`
+<https://github.com/epwalsh/pomo.nvim/blob/main/lua/pomo/notifier.lua>
+instances you |pomo-configure|. A timer can have any number of notifiers, which
+are essentially callbacks that fire on every tick of the timer (determined by
+|pomo-`update_interval`|) and each significant event, such as when the timer
+starts, completes, is stopped, or is hidden. **pomo.nvim** comes with several
+notifiers <https://github.com/epwalsh/pomo.nvim/tree/main/lua/pomo/notifiers>
+out-of-the-box, but it’s also easy to |pomo-create-your-own|.
+
 
 ==============================================================================
 1. Features                                                    *pomo-features*
@@ -28,8 +37,8 @@ COMMANDS                                                       *pomo-commands*
     - `:TimerStart 25m Work` to start a timer for 25 minutes called "Work".
     - `:TimerStart 10s` to start a timer for 10 seconds.
     - `:TimerStart 1h30m` to start a timer for an hour and a half.
-    pomo.nvim will recognize multiple forms of the time units, such as "m", "min",
-    "minute", or "minutes" for minutes.
+    **pomo.nvim** will recognize multiple forms of the time units, such as "m",
+    "min", "minute", or "minutes" for minutes.
 - `:TimerStop [TIMERID]` to stop a running timer, e.g. `:TimerStop 1`. If no ID
     is given, the latest timer is stopped.
 - `:TimerRepeat TIMELIMIT REPETITIONS [NAME]` to start a repeat timer,
@@ -46,9 +55,9 @@ COMMANDS                                                       *pomo-commands*
 ==============================================================================
 2. Setup                                                          *pomo-setup*
 
-To setup pomo.nvim you just need to call `require("pomo").setup({ ... })` with
-the desired options. Here are some examples using different plugin managers.
-The full set of |pomo-configuration-options| are listed below.
+To setup **pomo.nvim** you just need to call `require("pomo").setup({ ... })`
+with the desired options. Here are some examples using different plugin
+managers. The full set of |pomo-configuration-options| are listed below.
 
 
 USING LAZY.NVIM                                         *pomo-using-lazy.nvim*
@@ -101,13 +110,20 @@ read each option carefully and customize it to your needs:
       -- How often the notifiers are updated.
       update_interval = 1000,
 
-      -- Configure the notifiers to use for each timer that's created.
+      -- Configure the default notifiers to use for each timer.
+      -- You can also configure different notifiers for timers given specific names, see
+      -- the 'timers' field below.
       notifiers = {
-        -- The "Default" timer uses 'nvim-notify' to continuously display the timer
+        -- The "Default" notifier uses 'vim.notify' and works best when you have 'nvim-notify' installed.
         {
           name = "Default",
           opts = {
-            sticky = true,  -- set to false if you don't want to see the timer the whole time
+            -- With 'nvim-notify', when 'sticky = true' you'll have a live timer pop-up
+            -- continuously displayed. If you only want a pop-up notification when the timer starts
+            -- and finishes, set this to false.
+            sticky = true,
+
+            -- Configure the display icons:
             title_icon = "󱎫",
             text_icon = "󰄉",
             -- Replace the above with these if you don't have a patched font:
@@ -118,6 +134,7 @@ read each option carefully and customize it to your needs:
 
         -- The "System" notifier sends a system notification when the timer is finished.
         -- Currently this is only available on MacOS.
+        -- Tracking: https://github.com/epwalsh/pomo.nvim/issues/3
         { name = "System" },
 
         -- You can also define custom notifiers by providing an "init" function instead of a name.
@@ -127,7 +144,8 @@ read each option carefully and customize it to your needs:
 
       -- Override the notifiers for specific timer names.
       timers = {
-        -- For example, use only the "System" notifier when you create a timer called "Break"
+        -- For example, use only the "System" notifier when you create a timer called "Break",
+        -- e.g. ':TimerStart 2m Break'.
         Break = {
           { name = "System" },
         },
@@ -194,7 +212,7 @@ For example, here’s a simple notifier that just uses `print`:
     end
 <
 
-And then in the `notifiers` field of your pomo.nvim config, you’d add the
+And then in the `notifiers` field of your **pomo.nvim** config, you’d add the
 following entry:
 
 >lua
@@ -214,9 +232,9 @@ to have `nvim-notify` installed.
 
 LUALINE.NVIM                                               *pomo-lualine.nvim*
 
-pomo.nvim can easily be added to a section in your `lualine`. For example, this
-would extend the defaults for section X to include the next timer to finish
-(min time remaining):
+**pomo.nvim** can easily be added to a section in your `lualine`. For example,
+this would extend the defaults for section X to include the next timer to
+finish (min time remaining):
 
 >lua
     require("lualine").setup {