[T-238] enhance docs

docs/configuration/YAML-config.md

@@ -1,22 +1,20 @@
-# YAML configuration
-Instead of using command line arguments, it is possible to use a YAML file for configuration. \
-Then:
-- we don't need to repeat the options every time
-- the configuration can be easily shared
+# YAML Configuration
+
+You can use a YAML file to configure RefDocGen instead of specifying options on the command line. This approach makes it easy to reuse and share your configuration.
 
 The YAML file can be generated automatically using the `--save-config` flag (preferred) or created manually.
 It is recommended to name the file `refdocgen.yaml`.
 
-The structure of YAML and command line configuration is very similar:
+YAML configuration closely mirrors the command-line options:
 
-- all the keys in YAML have the same name as the matching command-line option (without the starting dashes), e.g. the `output-dir` key corresponds to the `--output-dir` option
-- the only mandatory key is the `input` (similar to the command-line configuration)
-- `save-config` option is not supported, as it does not make sense here
-- the default values are the same as in the command-line configuration
+- Each YAML key matches its corresponding command-line option (without leading dashes). For example, the `output-dir` key in YAML corresponds to the `--output-dir` option.
+- The only required key is `input`, just as on the command line.
+- The `save-config` option is not supported in YAML, as it doesn't make sense here
+- Default values are the same as those used for command-line options.
 
-## Examples
+## Example
 
-The following command results in creating the YAML displayed below:
+The following command generates a YAML configuration file as shown below:
 
 ```bash
 refdocgen MyLibrary.sln 

docs/configuration/basic-config.md

@@ -51,3 +51,4 @@ INPUT (pos. 0)                                  Required. The assembly, project,
 - [Custom static pages](./custom-static-pages.md)
 - [Doc versioning](./doc-versioning.md)
 - [YAML config](./YAML-config.md)
+- [Templates](../templates/available-templates.md)

docs/configuration/custom-static-pages.md

@@ -2,7 +2,7 @@
 
 You can include static pages (like *index* or *FAQ*) in the generated documentation, following the steps below:
 
-- create a directory (e.g., `static-pages/`) with `.html` or `.md` files
+- create a directory (e.g., `static-pages/`) with `.md` (preferred) or `.html` files
 - each file represents a page and should contain its the body content
 - run the generator with:
 
@@ -14,36 +14,41 @@ You can include static pages (like *index* or *FAQ*) in the generated documentat
 **Important: The static pages are not designed to offer the functionality of a full-fledged SSG. If you want more control over the pages, is advised to use an SSG, such as Jekyll, for user documentation.**
 
 Additional notes:
-- it is possible to use relative links between pages
+- It is possible to use relative links between pages. (Links to `.md` files are automatically updated to point to the correct output HTML files in the generated documentation.)
 - you can include images, JS, or any other resources in the static pages directory, and then reference them from the pages
-- to add custom CSS styles, put them into `/css/styles.css` and they will be included automatically (however, use custom styles only for minor tweaks, rather than completely changing the overall appearance of the page)
 - it is possible to put the pages (and other files) into subdirectories of the `static-pages/` directory (however, pages nested three or more levels deep will not appear in the top menu)
+- in case you use HTML pages, to add custom CSS styles, put them into `/css/styles.css` and they will be included automatically (however, use custom styles only for minor tweaks, rather than completely changing the overall appearance of the page)
+
 
 ## Example
 
-Directory structure:
+Example directory structure:
 ```
 static-pages/
-    index.html
-    FAQ.md
+    index.md
+    FAQ.html
 ```
 
-`index.html`
-```html
-<h1>
-    MyLibrary reference documentation
-</h1>
-<div>
-    This page contains the reference documentation of MyLibrary.
-</div>
+`index.md`
+```markdown
+# MyLibrary Reference Documentation
+
+This page contains the reference documentation for MyLibrary.
+
+## Installation
+To install, run `dotnet tool install my-library`.
 ```
 
-`FAQ.md`
-```markdown
-# FAQ
+`FAQ.html`
+```html
+<h1>FAQ</h1>
 
-## Q1: How to install the library?
-## A1: ...
+<h6>Q1: How to install the library?</h6>
+<div class="fw-light">A1: ...</div>
 ```
 
-![](../imgs/img.png)
+### Result
+The resulting static pages are shown below:
+
+![](../imgs/static-pages-index.png)
+![](../imgs/static-pages-faq.png)

docs/configuration/doc-versioning.md

@@ -1,13 +1,15 @@
 # Documentation versioning
 
-You can optionally generate versioned documentation, allowing users to switch between multiple versions.
-To do this, it is necessary to use the `--doc-version` option.
+You can optionally generate versioned documentation, which allows users to switch between multiple versions.
+To do this, use the `--doc-version` option.
 
-The version can be switched using the dropdown in the bottom menu.
+The version can then be switched using the dropdown menu at the bottom of the page, as illustrated below:
+
+![](../imgs/doc-version-example.png)
 
 ## Examples
 
-Generate two versions of the documentation, using these commands (the output directory needs to be the same):
+Generate two versions of the documentation using these commands (the output directory must be the same):
 
 ```bash
 refdocgen MyLibrary.dll --doc-version v1.0
@@ -17,12 +19,13 @@ refdocgen MyLibrary.dll --doc-version v1.1
 ```
 
 The documentation versions do not necessarily have to match the library versions.
-For instance, we may create two documentation versions, one showing the public API, and the other including even private members, as illustrated below:
+For example, you may create two documentation versions: one showing only the public API, and another including private members, as illustrated below:
 
 ```
 refdocgen MyLibrary.dll --doc-version v1.0-public
 refdocgen MyLibrary.dll --doc-version v1.0-private --min-visibility Private
 ```
 
-An example of versioned documentation can be found [here](https://vl-cz.github.io/refdocgen-demo-refdocgen/index.html). \
-Note that the documentations consists of two versions: `v-public` - displays only the public API and `v-private` displaying all types and members
+## Demo
+
+You can browse an example of versioned documentation [here](https://vl-cz.github.io/refdocgen-demo-example-library/index.html).

docs/index.md

@@ -73,6 +73,7 @@ refdocgen MyLibrary.sln
 - [Custom static pages](./configuration/custom-static-pages.md)
 - [Doc versioning](./configuration/doc-versioning.md)
 - [YAML config](./configuration/YAML-config.md)
+- [Templates](./templates/available-templates.md)
 
 ## Limitations 
 

docs/templates/available-templates.md

@@ -0,0 +1,6 @@
+# Templates
+Currently, only the `Default` documentation template is available.
+
+However, it is possible to create custom templates, as described in these articles:
+- [Creating custom Razor templates](./custom-Razor-templates.md)
+- [Custom template processor](./custom-template-processor.md)

docs/templates/custom-Razor-templates.md

@@ -0,0 +1,103 @@
+# Creating custom Razor templates
+
+You can use custom Razor templates with the `RazorTemplateProcessor` class to define your own documentation UI. The overall structure and output folder layout will remain the same as with the default templates.
+
+Follow these steps:
+
+1. Clone the `RefDocGen` project and navigate to the `src/RefDocGen/TemplateProcessors` folder.
+2. Copy the `Todo` subfolder and rename it to match your template design (e.g., `RazorMinimal`).
+3. Implement the eight Razor templates in the `Templates` subfolder. Each template includes a description of its intended usage and parameters.
+4. You may use any UI framework, but:
+	- All template parameters must remain unchanged.
+	- Member HTML elements on type pages should have their `id` set to the member ID.
+	- Place custom CSS and JavaScript in the `Templates/Static` folder. Use the provided `styles.css` and `script.js` files if possible.
+	- To support versioning, each page must include an element with `id="version-list"`. The available version identifiers will be inserted automatically and can be processed with JavaScript.
+	- Data such as field modifiers are represented as `LanguageSpecificData<T>`, which works as a dictionary indexed by language IDs. For C#, use the `CSharpData` property.
+
+## Configuration for XML tag transformation
+In addition to the templates, you must configure how the inner XML tags are transformed to HTML. There are two options:
+
+#### 1. Reuse the default configuration (recommended)
+
+The default configuration is represented by the `DocCommentHtmlConfiguration` class, which:
+    - Replaces XML tags (including `<seealso>` tags) with HTML elements (see Table 4.2 in the docs).
+    - These HTML elements are assigned CSS classes starting with `refdocgen`, as shown below:
+
+```
+XML Tag                                         HTML Representation
+-----------------------------------------       ---------------------------------------------------
+<para>                                      	<div class="refdocgen-paragraph">
+<list type="bullet">                        	<ul class="refdocgen-bullet-list">
+<list type="number">                        	<ol class="refdocgen-number-list">
+<list type="table">                         	<table class="refdocgen-table">
+<listheader>                                	<thead class="refdocgen-tableheader">
+<c>                                         	<code class="refdocgen-inline-code">
+<example>                                   	<div class="refdocgen-example">
+<paramref>                                  	<code class="refdocgen-paramref">
+<typeparamref>                              	<code class="refdocgentypeparamref">
+<see href="...">                            	<a href="..." class="refdocgen-seehref">
+<see langword="...">                        	<code class="refdocgen-seelangword">
+<seealso href="...">                        	<a href="..." class="refdocgenseealso-href">
+<code>                                      	<pre><code class="refdocgen-codeblock"></code></pre>
+<term> within a bullet/number list          	<span class="refdocgen-list-term">
+<description> within a bullet/number list   	<span class="refdocgen-listdescription">
+<item> within a bullet/number list          	<li class="refdocgen-list-item">
+<term> within a table                       	<td class="refdocgen-table-term">
+<description> within a table                	<td class="refdocgen-table-element">
+<item> within a table                       	<tr class="refdocgen-table-item">
+<see cref="..."> (link resolved)            	<a href="..." class="refdocgen-seecref">
+<seealso cref="..."> (link resolved)        	<a href="..." class="refdocgenseealso-cref">
+<see cref="..."> (link not resolved)        	<code class="refdocgen-see-cref-notfound">
+<seealso cref="..."> (link not resolved)    	<code class="refdocgen-seealso-crefnot-found">
+```
+
+All of these CSS classes can be styled as needed. For example:
+
+```css
+.refdocgen-paragraph {
+    /* custom styles */
+}
+```
+
+You can also inherit existing CSS classes using a CSS preprocessor, similar to how the default UI does it (see `TemplateProcessors/Default/Templates/Scss/styles.scss`).
+
+#### 2. Create a custom configuration
+
+For more control over the transformation, you can create a custom configuration.
+
+To customize how XML tags are transformed to HTML, implement the `IDocCommentHtmlConfiguration` interface in your template folder (e.g., `RazorMinimal`).
+Each property of this interface defines the target HTML for a specific XML tag. For example, to replace the `<c>` XML tag (inline code) with a `<span class="my-class">` element, set the corresponding property as follows:
+
+```csharp
+public XElement InlineCodeElement => new XElement("span",
+    new XAttribute("class", "my-class")
+);
+```
+
+## Registering Custom Templates
+
+After you create the templates and configuration, you must register the templates:
+1. Open `Program.cs` and find the comments marked `#ADD_TEMPLATE`.
+2. Add a new value to the `DocumentationTemplate` enum (e.g., `Minimal`).
+3. Instantiate your template processor and add it to the dictionary under the new enum value. Use `RazorTemplateProcessor.With` with your template types and configuration, passing the same constructor arguments as for `DefaultTemplateProcessor`.
+
+    ```csharp
+    RazorTemplateProcessor<
+        CustomObjectTypePage,
+        CustomDelegateTypePage,
+        CustomEnumTypePage,
+        CustomNamespacePage,
+        CustomAssemblyPage,
+        CustomApiHomePage,
+        CustomStaticPage,
+        CustomSearchPage
+    >.With(
+        new DocCommentHtmlConfiguration(),// the default configuration
+        // use a custom one, if provided
+        htmlRenderer,
+        availableLanguages,
+        config.StaticPagesDirectory,
+        config.Version)
+    ```
+
+4. You can now select your custom templates when generating documentation (by setting the `--template` option to `Minimal`).

docs/templates/custom-template-processor.md

@@ -0,0 +1,32 @@
+# Custom Template Processor
+
+You can customize the output by implementing your own template processor. This lets you use any templating language and output format (e.g., Markdown, HTML).
+
+To create a custom processor:
+1. In the RefDocGen project, add a new folder (e.g., `Custom`) under `TemplateProcessors`.
+2. Create a class (e.g., `CustomTemplateProcessor`) that implements the `ITemplateProcessor` interface. This interface requires a `ProcessTemplates` method, which generates documentation from the type registry.
+
+Recommendations:
+- Keep related code in the same folder or subfolders.
+- Pass extra parameters via the `CustomTemplateProcessor` constructor if needed.
+- Throw descriptive exceptions on errors.
+
+## Reusing Existing Classes
+
+If your documentation output is HTML, you can reuse the `StaticPageProcessor` class to collect static pages provided by the user. The `DocVersionManager` class may also be used in your custom template processor. The only requirement is that each HTML page must contain an element with `id="version-list"`, where the JSON array of available page versions will be automatically placed.
+
+You can also reuse the `DocCommentTransformer` class nd its default configuration (`DocCommentHtmlConfiguration`). Additionally, you may reuse the template model creators (`TemplateProcessors/Shared/TemplateModelCreators`) if both of the following conditions are met:
+
+1. The default template models (`TemplateProcessors/Shared/TemplateModels`) are suitable for your templates.
+2. The documentation output structure matches the default templates: each type, namespace, and assembly is represented by a separate page in the `api` folder, with page URLs equal to the corresponding template model ID. On type pages, each member element should have the `id` attribute set to the corresponding member ID.
+
+In this case, generating HTML is similar to the `RazorTemplateProcessor`, except you use a different templating language. Use the `RazorTemplateProcessor` class as a reference. Note that default template models store selected data as language-specific (use the `CSharpData` property to get the C# value).
+
+## Registering the Template Processor
+
+To register your custom template processor, follow these steps:
+
+1. In `Program.cs`, find the comments marked with `#ADD_TEMPLATE_PROCESSOR`.
+2. Add a new `DocumentationTemplate` enum value for your custom processor.
+3. Add your processor to the set of available documentation templates by inserting an instance into the dictionary, using the new enum value as the key.
+4. The processor will then be registered and appear in the list of available documentation templates displayed on the command line.

src/RefDocGen/RefDocGen.csproj

@@ -12,7 +12,7 @@
         <PackAsTool>true</PackAsTool>
         <ToolCommandName>refdocgen</ToolCommandName>
         <PackageOutputPath>./nupkg</PackageOutputPath>
-        <Version>1.0.5</Version>
+        <Version>1.0.6</Version>
         <Authors>Vojtěch Lengál</Authors>
         <Title>RefDocGen</Title>
         <Description>Reference Documentation Generator for .NET</Description>