chore(docs): auto generate docs

doc/obsidian.txt

@@ -32,6 +32,7 @@ own as well. You don’t necessarily need to use it alongside the Obsidian app.
     - |obsidian-configuration-options|
     - |obsidian-notes-on-configuration|
     - |obsidian-using-templates|
+    - |obsidian-using-obsidian.nvim-outside-of-a-workspace-/-obsidian-vault|
 - 🐞 |obsidian-known-issues|
 - ➕ |obsidian-contributing|
 
@@ -277,10 +278,9 @@ carefully and customize it to your needs:
 
 >lua
     {
-      -- A list of vault names and paths.
-      -- Each path should be the path to the vault root. If you use the Obsidian app,
-      -- the vault root is the parent directory of the `.obsidian` folder.
-      -- You can also provide configuration overrides for each workspace through the `overrides` field.
+      -- A list of workspace names, paths, and configuration overrides.
+      -- If you use the Obsidian app, the 'path' of a workspace should generally be
+      -- your vault root (where the `.obsidian` folder is located).
       workspaces = {
         {
           name = "personal",
@@ -300,10 +300,6 @@ carefully and customize it to your needs:
       -- 'workspaces'. For example:
       -- dir = "~/vaults/work",
 
-      -- Optional, set to true to use the current directory as a vault; otherwise
-      -- the first workspace is opened by default.
-      detect_cwd = false,
-
       -- Optional, if you keep notes in a specific subdirectory of your vault.
       notes_subdir = "notes",
 
@@ -708,6 +704,61 @@ to your config:
 <
 
 
+USING OBSIDIAN.NVIM OUTSIDE OF A WORKSPACE / OBSIDIAN VAULT*obsidian-using-obsidian.nvim-outside-of-a-workspace-/-obsidian-vault*
+
+It’s possible to configure obsidian.nvim to work on individual markdown files
+outside of a regular workspace / Obsidian vault by configuring a "dynamic"
+workspace. To do so you just need to add a special workspace with a function
+for the `path` field (instead of a string), which should return a _parent_
+directory of the current buffer. This tells obsidian.nvim to use that directory
+as the workspace `path` and `root` (vault root) when the buffer is not located
+inside another fixed workspace.
+
+For example, to extend the configuration above this way:
+
+>diff
+    {
+      workspaces = {
+         {
+           name = "personal",
+           path = "~/vaults/personal",
+         },
+         ...
+    +    {
+    +      name = "no-vault",
+    +      path = function()
+    +        -- alternatively use the CWD:
+    +        -- return assert(vim.fn.getcwd())
+    +        return assert(vim.fs.dirname(vim.api.nvim_buf_get_name(0)))
+    +      end,
+    +      overrides = {
+    +        notes_subdir = vim.NIL,  -- have to use 'vim.NIL' instead of 'nil'
+    +        completion = {
+    +          new_notes_location = "current_dir",
+    +        },
+    +        templates = {
+    +          subdir = vim.NIL,
+    +        },
+    +        disable_frontmatter = true,
+    +      },
+    +    },
+    +  },
+       ...
+    }
+<
+
+With this configuration, anytime you enter a markdown buffer outside of
+"~/vaults/personal" (or whatever your configured fixed vaults are),
+obsidian.nvim will switch to the dynamic workspace with the path / root set to
+the parent directory of the buffer.
+
+Please note that in order to avoid unexpected behavior (like a new directory
+being created for `notes_subdir`) it’s important to carefully set the
+workspace `overrides` options. And keep in mind that to reset a configuration
+option to `nil` you’ll have to use `vim.NIL` there instead of the builtin Lua
+`nil` due to the way Lua tables work.
+
+
 ==============================================================================
 4. Known Issues                                        *obsidian-known-issues*
 

doc/obsidian_api.txt

@@ -1,4 +1,4 @@
-*obsidian-api*
+*obidian-api*
 
 The Obsidian.nvim Lua API.
 
@@ -79,6 +79,17 @@ obsidian.Client
 Parameters ~
 {workspace} obsidian.Workspace
 
+------------------------------------------------------------------------------
+                                          *obsidian.Client.opts_for_workspace()*
+                `Client.opts_for_workspace`({self}, {workspace})
+Get the normalize opts for a given workspace.
+
+Parameters ~
+{workspace} obsidian.Workspace|?
+
+Return ~
+obsidian.config.ClientOpts
+
 ------------------------------------------------------------------------------
                                             *obsidian.Client.switch_workspace()*
                  `Client.switch_workspace`({self}, {workspace})
@@ -87,6 +98,18 @@ Switch to a different workspace.
 Parameters ~
 {workspace} `(obsidian.Workspace|string)` The workspace object or the name of an existing workspace.
 
+------------------------------------------------------------------------------
+                                                *obsidian.Client.path_is_note()*
+               `Client.path_is_note`({self}, {path}, {workspace})
+Check if a path represents a note in the workspace.
+
+Parameters ~
+{path} `(string|Path)`
+{workspace} obsidian.Workspace|?
+
+Return ~
+`(boolean)`
+
 ------------------------------------------------------------------------------
                                                   *obsidian.Client.vault_root()*
                     `Client.vault_root`({self}, {workspace})
@@ -120,9 +143,12 @@ Return ~
 
 ------------------------------------------------------------------------------
                                                *obsidian.Client.templates_dir()*
-                         `Client.templates_dir`({self})
+                  `Client.templates_dir`({self}, {workspace})
 Get the templates folder.
 
+Parameters ~
+{workspace} obsidian.Workspace|?
+
 Return ~
 Path| `(optional)`
 
@@ -649,55 +675,124 @@ Parameters ~
 Return ~
 `(boolean)` updated True if the buffer lines were updated, false otherwise.
 
+------------------------------------------------------------------------------
+Class ~
+{obsidian.workspace.WorkspaceSpec}
+
+Fields ~
+{path} `(string|Path|(fun():)` string|Path)
+{name} `(string|?)`
+{strict} `(boolean|?)` If true, the workspace root will be fixed to 'path' instead of the vault root (if different).
+{overrides} `(table|obsidian.config.ClientOpts|?)`
+
+------------------------------------------------------------------------------
+Class ~
+{obsidian.workspace.WorkspaceOpts}
+
+Fields ~
+{name} `(string|?)`
+{strict} `(boolean|?)` If true, the workspace root will be fixed to 'path' instead of the vault root (if different).
+{overrides} `(table|obsidian.config.ClientOpts|?)`
+
 ------------------------------------------------------------------------------
                                                             *obsidian.Workspace*
                                   `Workspace`
-Each workspace represents a vault and a set of configuration options specific to that vault.
+Each workspace represents a working directory (usually an Obsidian vault) along with
+a set of configuration options specific to the workspace.
+
+Workspaces are a little more general than Obsidian vaults as you can have a workspace
+outside of a vault or as a subdirectory of a vault.
 
 Class ~
 {obsidian.Workspace} : obsidian.ABC
 
 Fields ~
-{name} `(string)`
-{path} `(string)`
+{name} `(string)` An arbitrary name for the workspace.
+{path} `(string)` The normalized path to the workspace.
+{root} `(string)` The normalized path to the vault root of the workspace. This usually matches 'path'.
 {overrides} `(table|obsidian.config.ClientOpts|?)`
 
+------------------------------------------------------------------------------
+                                                    *obsidian.find_vault_root()*
+                         `find_vault_root`({base_dir})
+Find the vault root from a given directory.
+
+This will traverse the directory tree upwards until a '.obsidian/' folder is found to
+indicate the root of a vault, otherwise the given directory is used as-is.
+
+Parameters ~
+{base_dir} `(string|Path)`
+
+Return ~
+Path| `(optional)`
+
 ------------------------------------------------------------------------------
                                                       *obsidian.Workspace.new()*
-                  `Workspace.new`({name}, {path}, {overrides})
-Create a new workspace object. This assumes the workspace already exists on the filesystem.
+                        `Workspace.new`({path}, {opts})
+Create a new 'Workspace' object. This assumes the workspace already exists on the filesystem.
 
 Parameters ~
-{name} `(string)` Workspace name
-{path} `(string|Path)` Workspace path (will be normalized)
-{overrides} `(table|obsidian.config.ClientOpts|?)`
+{path} `(string|Path)` Workspace path.
+{opts} obsidian.workspace.WorkspaceOpts|?
+
+Return ~
+obsidian.Workspace
+
+------------------------------------------------------------------------------
+                                            *obsidian.Workspace.new_from_spec()*
+                       `Workspace.new_from_spec`({spec})
+Initialize a new 'Workspace' object from a workspace spec.
+
+Parameters ~
+{spec} obsidian.workspace.WorkspaceSpec
 
 Return ~
 obsidian.Workspace
 
 ------------------------------------------------------------------------------
                                              *obsidian.Workspace.new_from_cwd()*
-                           `Workspace.new_from_cwd`()
+                        `Workspace.new_from_cwd`({opts})
+Initialize a 'Workspace' object from the current working directory.
+
+Parameters ~
+{opts} obsidian.workspace.WorkspaceOpts|?
+
 Return ~
 obsidian.Workspace
 
 ------------------------------------------------------------------------------
-                                             *obsidian.Workspace.new_from_dir()*
-                        `Workspace.new_from_dir`({dir})
+                                             *obsidian.Workspace.new_from_buf()*
+                   `Workspace.new_from_buf`({bufnr}, {opts})
+Initialize a 'Workspace' object from the parent directory of the current buffer.
+
 Parameters ~
-{dir} `(string|Path)`
+{bufnr} `(integer|?)`
+{opts} obsidian.workspace.WorkspaceOpts|?
 
 Return ~
 obsidian.Workspace
 
 ------------------------------------------------------------------------------
-                                   *obsidian.Workspace.get_workspace_from_cwd()*
-                `Workspace.get_workspace_from_cwd`({workspaces})
+                                    *obsidian.Workspace.get_workspace_for_dir()*
+           `Workspace.get_workspace_for_dir`({cur_dir}, {workspaces})
+Get the workspace corresponding to the directory (or a parent of), if there
+is one.
+
+Parameters ~
+{cur_dir} `(string|Path)`
+{workspaces} obsidian.workspace.WorkspaceSpec[]
+
+Return ~
+obsidian.Workspace| `(optional)`
+
+------------------------------------------------------------------------------
+                                    *obsidian.Workspace.get_workspace_for_cwd()*
+                `Workspace.get_workspace_for_cwd`({workspaces})
 Get the workspace corresponding to the current working directory (or a parent of), if there
 is one.
 
 Parameters ~
-{workspaces} obsidian.Workspace[]
+{workspaces} obsidian.workspace.WorkspaceSpec[]
 
 Return ~
 obsidian.Workspace| `(optional)`
@@ -708,7 +803,7 @@ obsidian.Workspace| `(optional)`
 Returns the default workspace.
 
 Parameters ~
-{workspaces} `(table<obsidian.Workspace>)`
+{workspaces} obsidian.workspace.WorkspaceSpec[]
 
 Return ~
 `(obsidian.Workspace|nil)`
@@ -722,6 +817,6 @@ Parameters ~
 {opts} obsidian.config.ClientOpts
 
 Return ~
-obsidian.Workspace
+obsidian.Workspace| `(optional)`
 
  vim:tw=78:ts=8:noet:ft=help:norl: