doc: update docs

netpyoung · Dec 10, 2024 · f54b71a · f54b71a
1 parent 2701042
commit f54b71a
Show file tree

Hide file tree

Showing 7 changed files with 160 additions and 65 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1 @@
+# ChangeLog
diff --git a/README.md b/README.md
@@ -32,6 +32,7 @@ dotnet tool install --global dotnet-release-note
 - use [Spectre.Console](https://spectreconsole.net/) for console output.
 - use [Spectre.Console.Cli](https://spectreconsole.net/cli/) for parse args.
 - use [SmartFormat](https://github.com/axuno/SmartFormat) for format string.
+- use [sebastienros/fluid](https://github.com/sebastienros/fluid) for [liquid](https://shopify.github.io/liquid/)
 
 ## License
 

diff --git a/docfx/docs/changelog.md b/docfx/docs/changelog.md
@@ -0,0 +1 @@
+[!include[Default](~/../CHANGELOG.md)]
diff --git a/docfx/docs/concept.md b/docfx/docs/concept.md
@@ -1,27 +1,30 @@
 # Concept
 
-news fragments/newsfiles/topfiles
-
-## Example
-
-``` txt
-USAGE:
-    dotnet release-note [OPTIONS] <COMMAND>
-
-EXAMPLES:
-    dotnet release-note init
-    dotnet release-note create --edit
-    dotnet release-note create 1.added.md --content "Hello World"
-    dotnet release-note build --version 1.0.0
-    dotnet release-note check
-
-OPTIONS:
-    -h, --help    Prints help information
-
-COMMANDS:
-    init       Init release-note setup
-    create     Create a new fragment
-    preview    Preview a release note
-    build      Build a release note
-    check      Checks files changed
-```
+## Flow
+
+``` mermaid
+flowchart LR
+
+
+Files["`
+    1.added.md
+    2.fixed.md
+    3.security.md
+    ...
+`"]
+
+Renderer{Renderer}
+Output[ChangeLog.md]
+
+Files --> Fragments
+
+subgraph ReleaseNoteMaker
+    Fragments -->|Arragne| Model(Model)
+    Model --> Renderer
+end
+
+Renderer -->|t4    | Output
+Renderer -->|liquid| Output
+
+style Files text-align:left
+```
diff --git a/docfx/docs/setup/template.md b/docfx/docs/setup/template.md
@@ -1,22 +1,18 @@
 # Template
 
-``` mermaid
-flowchart LR
+- support
+  - [T4 template](https://learn.microsoft.com/en-us/visualstudio/modeling/code-generation-and-t4-text-templates)
+  - [liquid](https://shopify.github.io/liquid/)
 
-A[Hard] -->|Text| B(Round)
-B --> C{Decision}
-C -->|One| D[Result 1]
-C -->|Two| E[Result 2]
-```
 
 
-# [Template.tt](#tab/t4)
+## [Template.tt](#tab/t4)
 
 [!code-csharp[Default](~/../NF.Tool.ReleaseNoteMaker/NF.Tool.ReleaseNoteMaker.CLI/res/Template.tt)]
 
-# [Template.liquid](#tab/liquid)
+## [Template.liquid](#tab/liquid)
 
-Content for Windows...
+[!code-liquid[Default](~/../NF.Tool.ReleaseNoteMaker/NF.Tool.ReleaseNoteMaker.CLI/res/Template.liquid)]
 
 ---
 

diff --git a/docfx/docs/toc.yml b/docfx/docs/toc.yml
@@ -12,5 +12,6 @@
   items:
     - href: setup/config.md
     - href: setup/template.md
+- href: changelog.md
 - name: 📦 Github
   href: https://github.com/netpyoung/NF.Tool.ReleaseNoteMaker
diff --git a/docfx/docs/tutorial.md b/docfx/docs/tutorial.md
@@ -1,54 +1,115 @@
 # Tutorial
 
+
+0. Install
+
+``` sh
+$ dotnet tool install --global dotnet-release-note
+```
+
+``` sh
+$ dotnet release-note
+USAGE:
+    dotnet release-note [OPTIONS] <COMMAND>
+
+EXAMPLES:
+    dotnet release-note init
+    dotnet release-note create --edit
+    dotnet release-note create 1.added.md --content "Hello World"
+    dotnet release-note build --version 1.0.0
+    dotnet release-note check
+
+OPTIONS:
+    -h, --help    Prints help information
+
+COMMANDS:
+    init       Init release-note setup
+    create     Create a new fragment
+    preview    Preview a release note
+    build      Build a release note
+    check      Checks files changed
+```
+
+2. Init
+
 ``` sh
 $ dotnet release-note init
 Initialized
 ./
 ├── ReleaseNote.config.toml
 └── ChangeLog.d/
     └── Template.tt
-$ dotnet release-note preview
-# x.x.x (2024-12-09)
+```
+
+3. Create a changelog entry:
+
+    Add a new file in the changelog/ directory, named with the issue or pull request number and type.
 
+``` sh
+dotnet release-note create --content "Added a cool feature!"          1.added.md
+dotnet release-note create --content "Changed a behavior!"            2.changed.md
+dotnet release-note create --content "Deprecated a module!"           3.deprecated.md
+dotnet release-note create --content "Removed a square feature!"      4.removed.md
+dotnet release-note create --content "Fixed a bug!"                   5.fixed.md
+dotnet release-note create --content "Fixed a security issue!"        6.security.md
+dotnet release-note create --content "Fixed a security issue!"        7.security.md
+dotnet release-note create --content "A fix without an issue number!" +something-unique.fixed.md
+```
 
+``` sh
+ChangeLog.d/
+├── 1.added.md
+├── 2.changed.md
+├── 3.deprecated.md
+├── 4.removed.md
+├── 5.fixed.md
+├── 6.security.md
+├── 7.security.md
+└── +something-unique.fixed.md
+```
 
-$ dotnet release-note create 123.feature.md
-Created news fragment at 123.feature.md
+4. Preview changelog
 
+``` sh
 $ dotnet release-note preview
-# x.x.x (2024-12-09)
+dotnet release-note preview
+# x.x.x (2024-12-10)
 
 
 ## Main
 
-### Features
+### Security
 
-- Add your info here (#123)
+- Fixed a security issue! (#6, #7)
 
+### Removed
 
+- Removed a square feature! (#4)
 
-$ dotnet release-note create
-Issue Name :
-ex) + / +hello / 123 / baz.1.2
-Default: (+): 456
-Created news fragment at C:\Users\pyoung\temp2\ChangeLog.d\456.changed.md
+### Deprecated
 
-$ dotnet release-note preview
-# x.x.x (2024-12-09)
+- Deprecated a module! (#3)
 
+### Added
 
-## Main
+- Added a cool feature! (#1)
 
 ### Changed
 
-- Add your info here (#456)
+- Changed a behavior! (#2)
 
-### Features
+### Fixed
+
+- Fixed a bug! (#5)
+- A fix without an issue number!
 
-- Add your info here (#123)
 
 
+```
+
+5. Build changelog
 
+``` sh
 $ dotnet release-note build --version 1.0.0
 * Finding news fragments...
 * Loading template...
@@ -58,13 +119,53 @@ $ dotnet release-note build --version 1.0.0
 * Staging newsfile...
     ➕ C:\Users\pyoung\temp2\CHANGELOG.md
 I want to remove the following files:
-    ❌ C:\Users\pyoung\temp2\ChangeLog.d\123.feature.md
-    ❌ C:\Users\pyoung\temp2\ChangeLog.d\456.changed.md
+    ❌ C:\Users\pyoung\temp2\ChangeLog.d\+something-unique.fixed.md
+    ❌ C:\Users\pyoung\temp2\ChangeLog.d\1.added.md
+    ❌ C:\Users\pyoung\temp2\ChangeLog.d\2.changed.md
+    ❌ C:\Users\pyoung\temp2\ChangeLog.d\3.deprecated.md
+    ❌ C:\Users\pyoung\temp2\ChangeLog.d\4.removed.md
+    ❌ C:\Users\pyoung\temp2\ChangeLog.d\5.fixed.md
+    ❌ C:\Users\pyoung\temp2\ChangeLog.d\6.security.md
+    ❌ C:\Users\pyoung\temp2\ChangeLog.d\7.security.md
 Is it okay if I remove those files? [y/n] (y): y
 * Removing news fragments...
 * Done!
-$
+```
+
+```
 $ cat .\CHANGELOG.md
+cat CHANGELOG.md
+# 1.0.0 (2024-12-10)
+
+
+## Main
+
+### Security
+
+- Fixed a security issue! (#6, #7)
+
+### Removed
+
+- Removed a square feature! (#4)
+
+### Deprecated
+
+- Deprecated a module! (#3)
+
+### Added
+
+- Added a cool feature! (#1)
+
+### Changed
+
+- Changed a behavior! (#2)
+
+### Fixed
+
+- Fixed a bug! (#5)
+- A fix without an issue number!
+
+
 # 1.0.0 (2024-12-09)
 
 
@@ -78,12 +179,3 @@ $ cat .\CHANGELOG.md
 
 - Add your info here (#123)
 ```
-
-dotnet release-note create --content "Added a cool feature!"          1.added.md
-dotnet release-note create --content "Changed a behavior!"            2.changed.md
-dotnet release-note create --content "Deprecated a module!"           3.deprecated.md
-dotnet release-note create --content "Removed a square feature!"      4.removed.md
-dotnet release-note create --content "Fixed a bug!"                   5.fixed.md
-dotnet release-note create --content "Fixed a security issue!"        6.security.md
-dotnet release-note create --content "Fixed a security issue!"        7.security.md
-dotnet release-note create --content "A fix without an issue number!" +something-unique.fixed.md