support locations relative to search paths

CMakeLists.txt

@@ -440,7 +440,7 @@ if (MRDOCS_BUILD_TESTS)
             DEPENDS mrdocs.rnc)
         add_custom_target(mrdocs_rng ALL DEPENDS mrdocs.rng)
 
-        file(GLOB_RECURSE XML_SOURCES CONFIGURE_DEPENDS test-files/*.xml)
+        file(GLOB_RECURSE XML_SOURCES CONFIGURE_DEPENDS test-files/golden-tests/*.xml)
         add_test(NAME xml-lint
                  COMMAND ${LIBXML2_XMLLINT_EXECUTABLE} --dropdtd --noout
                      --relaxng ${CMAKE_CURRENT_BINARY_DIR}/mrdocs.rng ${XML_SOURCES}

docs/modules/ROOT/pages/generators.adoc

@@ -862,25 +862,25 @@ The location object has the following properties:
 |===
 |Property |Type| Description
 
-| `path`
+| `fullPath`
 | `string`
-| The path of the source file.
+| The full path of the source file.
 
-| `file`
+| `shortPath`
 | `string`
-| The filename of the source file.
+| The path of the source file relative to the search directories.
+
+| `sourcePath`
+| `string`
+| The path of the source file relative to the `source-root`.
 
 | `line`
 | `integer`
-| The line number of the symbol.
-
-| `kind`
-| `string`
-| The kind of file (e.g., `source`, `system`, `other`).
+| The line number of the symbol at this location.
 
 | `documented`
 | `bool`
-| Whether the symbol is documented.
+| Whether the symbol is documented at this location.
 |===
 
 [#tparam-fields]

docs/mrdocs.schema.json

@@ -225,7 +225,7 @@
     },
     "source-root": {
       "default": "<config-dir>",
-      "description": "Path to the root directory of the source code. This path is used as a default for input files and a base for relative paths formed from absolute paths.",
+      "description": "Path to the root directory of the source code. This path is used as a default for input files and a base for relative paths formed from absolute paths. This should typically be the root directory of the git project, as relative paths formed from it can be used to create links to these source files in the repository. Templates use the `base-url` option to create links to the source code.",
       "title": "Path to the root directory of the source code",
       "type": "string"
     },

include/mrdocs/Metadata/Source.hpp

@@ -51,36 +51,36 @@ struct MRDOCS_DECL
 {
     /** The full file path
     */
-    std::string Path;
+    std::string FullPath;
 
-    /** Name of the file
+    /** The file path relative to one of the search directories
     */
-    std::string Filename;
+    std::string ShortPath;
+
+    /** The file path relative to the source-root directory
+     */
+    std::string SourcePath;
 
     /** Line number within the file
     */
     unsigned LineNumber = 0;
 
-    /** The kind of file this is
-    */
-    FileKind Kind = FileKind::Source;
-
     /** Whether this location has documentation.
     */
     bool Documented = false;
 
     //--------------------------------------------
 
     Location(
-        std::string_view const filepath = {},
-        std::string_view const filename = {},
+        std::string_view const full_path = {},
+        std::string_view const short_path = {},
+        std::string_view const source_path = {},
         unsigned const line = 0,
-        FileKind const kind = FileKind::Source,
         bool const documented = false)
-        : Path(filepath)
-        , Filename(filename)
+        : FullPath(full_path)
+        , ShortPath(short_path)
+        , SourcePath(source_path)
         , LineNumber(line)
-        , Kind(kind)
         , Documented(documented)
     {
     }
@@ -98,7 +98,7 @@ struct LocationEmptyPredicate
     constexpr bool operator()(
         Location const& loc) const noexcept
     {
-        return loc.Filename.empty();
+        return loc.ShortPath.empty();
     }
 };
 

include/mrdocs/Support/Path.hpp

@@ -241,6 +241,12 @@ std::string
 makePosixStyle(
     std::string_view pathName);
 
+/** Check if the path is posix style.
+*/
+MRDOCS_DECL
+bool
+isPosixStyle(std::string_view pathName);
+
 /** Return the filename with a new or different extension.
 
     @param fileName The absolute or relative path

mrdocs.rnc

@@ -326,7 +326,9 @@ grammar
     Location =
         element file
         {
-            attribute path {text},
+            # attribute full-path {text},
+            attribute short-path {text},
+            attribute source-path {text},
             attribute line {text},
             attribute class {"def"} ?,
             empty

share/mrdocs/addons/generator/common/partials/location/source.hbs

@@ -11,9 +11,9 @@
 
 --}}
 Declared in {{#>markup/code~}}
-    {{ str "<" }}{{#unless (and @root.config.base-url (eq dcl.kind "source"))~}}
-        {{dcl.file}}
+    {{ str "<" }}{{#if (and @root.config.base-url dcl.shortPath dcl.sourcePath)~}}
+        {{#>markup/a href=(concat @root.config.base-url dcl.sourcePath '#L' dcl.line)}}{{dcl.shortPath}}{{/markup/a}}
     {{~else~}}
-        {{#>markup/a href=(concat @root.config.base-url dcl.file '#L' dcl.line)}}{{dcl.file}}{{/markup/a}}
-    {{~/unless~}}{{ str ">" }}
+        {{dcl.shortPath}}
+    {{~/if~}}{{ str ">" }}
 {{~/markup/code}}