add documentation for the plugin system

daynin · Mar 29, 2023 · 6859736 · 6859736
1 parent f1d9a91
commit 6859736
Show file tree

Hide file tree

Showing 9 changed files with 105 additions and 32 deletions.
diff --git a/book.toml b/book.toml
@@ -12,5 +12,5 @@ extra-watch-dirs = []
 use-default-preprocessors = true
 
 [preprocessor.mermaid]
-command = "./target/debug/fundoc -e"
+command = "fundoc -e"
 
diff --git a/docs/404.html b/docs/404.html
@@ -84,7 +84,7 @@
 
         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
             <div class="sidebar-scrollbox">
-                <ol class="chapter"><li class="chapter-item expanded "><a href="configuration.html"><strong aria-hidden="true">1.</strong> Configuration</a></li><li class="chapter-item expanded "><a href="syntax.html"><strong aria-hidden="true">2.</strong> Syntax</a></li></ol>
+                <ol class="chapter"><li class="chapter-item expanded "><a href="configuration.html"><strong aria-hidden="true">1.</strong> Configuration</a></li><li class="chapter-item expanded "><a href="plugins.html"><strong aria-hidden="true">2.</strong> Plugins</a></li><li class="chapter-item expanded "><a href="syntax.html"><strong aria-hidden="true">3.</strong> Syntax</a></li></ol>
             </div>
             <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
         </nav>

diff --git a/docs/configuration.html b/docs/configuration.html
@@ -83,7 +83,7 @@
 
         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
             <div class="sidebar-scrollbox">
-                <ol class="chapter"><li class="chapter-item expanded "><a href="configuration.html" class="active"><strong aria-hidden="true">1.</strong> Configuration</a></li><li class="chapter-item expanded "><a href="syntax.html"><strong aria-hidden="true">2.</strong> Syntax</a></li></ol>
+                <ol class="chapter"><li class="chapter-item expanded "><a href="configuration.html" class="active"><strong aria-hidden="true">1.</strong> Configuration</a></li><li class="chapter-item expanded "><a href="plugins.html"><strong aria-hidden="true">2.</strong> Plugins</a></li><li class="chapter-item expanded "><a href="syntax.html"><strong aria-hidden="true">3.</strong> Syntax</a></li></ol>
             </div>
             <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
         </nav>
@@ -169,13 +169,13 @@ <h1 id="configuration"><a class="header" href="#configuration">Configuration</a>
 </li>
 </ul>
 <p>For example a microservices architecture:</p>
-<pre class="mermaid">
+<p>{{ #mermaid
 flowchart TD;
-  A[Documentaion repo] --> B[A repo of Mecroservice 1];
-  A --> C[A repo of Mecroservice 2];
-  A --> D[A repo of Mecroservice 3];
-</pre><script type="module"> import mermaid from "https://cdn.jsdelivr.net/npm/[email protected]/+esm"; mermaid.initialize({}); </script>
-<p><a href="https://github.com/daynin/fundoc/blob/master/#L36-L47">[~]</a></p>
+A[Documentaion repo] --&gt; B[A repo of Mecroservice 1];
+A --&gt; C[A repo of Mecroservice 2];
+A --&gt; D[A repo of Mecroservice 3];
+}}
+<a href="https://github.com/daynin/fundoc/blob/master/#L36-L47">[~]</a></p>
 <ul>
 <li>
 <p><code>repository_host</code> - an http url which will be used for creating a link to a file in a
@@ -217,7 +217,7 @@ <h1 id="configuration"><a class="header" href="#configuration">Configuration</a>
                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
 
-                            <a rel="next" href="syntax.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                            <a rel="next" href="plugins.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                 <i class="fa fa-angle-right"></i>
                             </a>
 
@@ -228,7 +228,7 @@ <h1 id="configuration"><a class="header" href="#configuration">Configuration</a>
 
             <nav class="nav-wide-wrapper" aria-label="Page navigation">
 
-                    <a rel="next" href="syntax.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                    <a rel="next" href="plugins.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                         <i class="fa fa-angle-right"></i>
                     </a>
             </nav>

diff --git a/docs/index.html b/docs/index.html
@@ -83,7 +83,7 @@
 
         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
             <div class="sidebar-scrollbox">
-                <ol class="chapter"><li class="chapter-item expanded "><a href="configuration.html" class="active"><strong aria-hidden="true">1.</strong> Configuration</a></li><li class="chapter-item expanded "><a href="syntax.html"><strong aria-hidden="true">2.</strong> Syntax</a></li></ol>
+                <ol class="chapter"><li class="chapter-item expanded "><a href="configuration.html" class="active"><strong aria-hidden="true">1.</strong> Configuration</a></li><li class="chapter-item expanded "><a href="plugins.html"><strong aria-hidden="true">2.</strong> Plugins</a></li><li class="chapter-item expanded "><a href="syntax.html"><strong aria-hidden="true">3.</strong> Syntax</a></li></ol>
             </div>
             <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
         </nav>
@@ -169,13 +169,13 @@ <h1 id="configuration"><a class="header" href="#configuration">Configuration</a>
 </li>
 </ul>
 <p>For example a microservices architecture:</p>
-<pre class="mermaid">
+<p>{{ #mermaid
 flowchart TD;
-  A[Documentaion repo] --> B[A repo of Mecroservice 1];
-  A --> C[A repo of Mecroservice 2];
-  A --> D[A repo of Mecroservice 3];
-</pre><script type="module"> import mermaid from "https://cdn.jsdelivr.net/npm/[email protected]/+esm"; mermaid.initialize({}); </script>
-<p><a href="https://github.com/daynin/fundoc/blob/master/#L36-L47">[~]</a></p>
+A[Documentaion repo] --&gt; B[A repo of Mecroservice 1];
+A --&gt; C[A repo of Mecroservice 2];
+A --&gt; D[A repo of Mecroservice 3];
+}}
+<a href="https://github.com/daynin/fundoc/blob/master/#L36-L47">[~]</a></p>
 <ul>
 <li>
 <p><code>repository_host</code> - an http url which will be used for creating a link to a file in a
@@ -217,7 +217,7 @@ <h1 id="configuration"><a class="header" href="#configuration">Configuration</a>
                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
 
-                            <a rel="next" href="syntax.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                            <a rel="next" href="plugins.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                 <i class="fa fa-angle-right"></i>
                             </a>
 
@@ -228,7 +228,7 @@ <h1 id="configuration"><a class="header" href="#configuration">Configuration</a>
 
             <nav class="nav-wide-wrapper" aria-label="Page navigation">
 
-                    <a rel="next" href="syntax.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                    <a rel="next" href="plugins.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                         <i class="fa fa-angle-right"></i>
                     </a>
             </nav>

diff --git a/docs/print.html b/docs/print.html
@@ -84,7 +84,7 @@
 
         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
             <div class="sidebar-scrollbox">
-                <ol class="chapter"><li class="chapter-item expanded "><a href="configuration.html"><strong aria-hidden="true">1.</strong> Configuration</a></li><li class="chapter-item expanded "><a href="syntax.html"><strong aria-hidden="true">2.</strong> Syntax</a></li></ol>
+                <ol class="chapter"><li class="chapter-item expanded "><a href="configuration.html"><strong aria-hidden="true">1.</strong> Configuration</a></li><li class="chapter-item expanded "><a href="plugins.html"><strong aria-hidden="true">2.</strong> Plugins</a></li><li class="chapter-item expanded "><a href="syntax.html"><strong aria-hidden="true">3.</strong> Syntax</a></li></ol>
             </div>
             <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
         </nav>
@@ -170,13 +170,13 @@ <h1 id="configuration"><a class="header" href="#configuration">Configuration</a>
 </li>
 </ul>
 <p>For example a microservices architecture:</p>
-<pre class="mermaid">
+<p>{{ #mermaid
 flowchart TD;
-  A[Documentaion repo] --> B[A repo of Mecroservice 1];
-  A --> C[A repo of Mecroservice 2];
-  A --> D[A repo of Mecroservice 3];
-</pre><script type="module"> import mermaid from "https://cdn.jsdelivr.net/npm/[email protected]/+esm"; mermaid.initialize({}); </script>
-<p><a href="https://github.com/daynin/fundoc/blob/master/#L36-L47">[~]</a></p>
+A[Documentaion repo] --&gt; B[A repo of Mecroservice 1];
+A --&gt; C[A repo of Mecroservice 2];
+A --&gt; D[A repo of Mecroservice 3];
+}}
+<a href="https://github.com/daynin/fundoc/blob/master/#L36-L47">[~]</a></p>
 <ul>
 <li>
 <p><code>repository_host</code> - an http url which will be used for creating a link to a file in a
@@ -212,6 +212,35 @@ <h1 id="configuration"><a class="header" href="#configuration">Configuration</a>
 <p>In case when you don't write the enable-comment all text from disable comment until the end of
 the file will be ignored
 <a href="https://github.com/daynin/fundoc/blob/master/#L285-L291">[~]</a></p>
+<div style="break-before: page; page-break-before: always;"></div><h1 id="plugins"><a class="header" href="#plugins">Plugins</a></h1>
+<p>You can create a plugin for Fundoc to convert any text block of the following code in documentation:</p>
+<pre><code>{{ #your-plugin-name any text here }}
+
+</code></pre>
+<p>This insertion can be multiline as well:</p>
+<pre><code>{{ #your-plugin-name
+ any text here
+}}
+
+</code></pre>
+<p>To create a plugin for parsing these blocks, you should add a file called <code>your-plugin-name.html.lua</code> into the plugins folder. By default, it's <code>./plugins</code>, but it's possible to change it in the config file.
+Then you should add the following strings into the <code>book.toml</code> file:</p>
+<pre><code class="language-toml">[preprocessor.your-plugin-name]
+command = &quot;fundoc -e&quot;
+</code></pre>
+<p>The <code>-e</code> artument runs Fundoc in mdBook extension mode.</p>
+<p>And in your your-plugin-name.html.lua, you should implement text transformation like this:</p>
+<pre><code class="language-lua">function transform(text)
+  result = 'transformted text' 
+end
+</code></pre>
+<p>Fundoc calls the <code>transform</code> function and passes the parsed text from the marked text block. You can transform it in any way you want.
+<a href="https://github.com/daynin/fundoc/blob/master/src/plugins.rs#L16-L52">[~]</a></p>
+<blockquote>
+<p>[note] mdBook runs Fundoc twice. The first time fundoc should exit with 0 code. The
+second time Fundoc transforms the text.
+<a href="https://github.com/daynin/fundoc/blob/master/#L71-L73">[~]</a></p>
+</blockquote>
 <div style="break-before: page; page-break-before: always;"></div><h1 id="syntax"><a class="header" href="#syntax">Syntax</a></h1>
 <p><code>@Article &lt;Article name&gt;</code> is for marking documentation sections to tell in which article this section should
 be merged. You can use <code>markdown</code> syntax in documentation sections.</p>

diff --git a/docs/searchindex.js b/docs/searchindex.js
diff --git a/docs/searchindex.json b/docs/searchindex.json
diff --git a/docs/syntax.html b/docs/syntax.html
@@ -83,7 +83,7 @@
 
         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
             <div class="sidebar-scrollbox">
-                <ol class="chapter"><li class="chapter-item expanded "><a href="configuration.html"><strong aria-hidden="true">1.</strong> Configuration</a></li><li class="chapter-item expanded "><a href="syntax.html" class="active"><strong aria-hidden="true">2.</strong> Syntax</a></li></ol>
+                <ol class="chapter"><li class="chapter-item expanded "><a href="configuration.html"><strong aria-hidden="true">1.</strong> Configuration</a></li><li class="chapter-item expanded "><a href="plugins.html"><strong aria-hidden="true">2.</strong> Plugins</a></li><li class="chapter-item expanded "><a href="syntax.html" class="active"><strong aria-hidden="true">3.</strong> Syntax</a></li></ol>
             </div>
             <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
         </nav>
@@ -216,7 +216,7 @@ <h1 id="syntax"><a class="header" href="#syntax">Syntax</a></h1>
 
                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
-                            <a rel="prev" href="configuration.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                            <a rel="prev" href="plugins.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                 <i class="fa fa-angle-left"></i>
                             </a>
 
@@ -227,7 +227,7 @@ <h1 id="syntax"><a class="header" href="#syntax">Syntax</a></h1>
             </div>
 
             <nav class="nav-wide-wrapper" aria-label="Page navigation">
-                    <a rel="prev" href="configuration.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                    <a rel="prev" href="plugins.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                         <i class="fa fa-angle-left"></i>
                     </a>
 

diff --git a/src/plugins.rs b/src/plugins.rs
@@ -12,6 +12,45 @@ pub struct Plugins {
     config: config::Config,
 }
 
+/**
+ * @Article Plugins
+ *
+ * You can create a plugin for Fundoc to convert any text block of the following code in documentation:
+ *
+ * ```
+ * {{ #your-plugin-name any text here }}
+ *
+ * ```
+ *
+ * This insertion can be multiline as well:
+ *
+ * ```
+ * {{ #your-plugin-name
+ *  any text here
+ * }}
+ * 
+ * ```
+ *
+ * To create a plugin for parsing these blocks, you should add a file called `your-plugin-name.html.lua` into the plugins folder. By default, it's `./plugins`, but it's possible to change it in the config file.
+ * Then you should add the following strings into the `book.toml` file:
+ *
+ * ```toml
+ * [preprocessor.your-plugin-name]
+ * command = "fundoc -e"
+ * ```
+ * The `-e` artument runs Fundoc in mdBook extension mode.
+ *
+ * And in your your-plugin-name.html.lua, you should implement text transformation like this:
+ *
+ * ```lua
+ * function transform(text)
+ *   result = 'transformted text' 
+ * end
+ * ```
+ *
+ * Fundoc calls the `transform` function and passes the parsed text from the marked text block. You can transform it in any way you want.
+ *
+ */
 impl Plugins {
     pub fn new(lua_runtime: lua_runtime::LuaRuntime, config: config::Config) -> Self {
         Self {
@@ -28,6 +67,11 @@ impl Plugins {
         let paths = fs::read_dir(self.config.plugins_dir.as_ref().unwrap());
         let args: Vec<String> = env::args().collect();
 
+        /**
+         * @Article Plugins
+         * > [note] mdBook runs Fundoc twice. The first time fundoc should exit with 0 code. The
+         * second time Fundoc transforms the text.
+         */
         if args.len() > 3 {
             process::exit(0x0100);
         }