build based on e4c9e8e

dev/index.html

@@ -21,4 +21,4 @@
 │   └── TestImage.png
 ├── index.html
 └── pages
-    └── blah.html</code></pre><p>Calling <code>serve()</code> from within this directory starts a file server. It serves the contents of the directory as a static site, with the folder structure defining the paths of the URLs. That is, the file <code>blah.html</code> can be viewed at <code>/pages/blah.html</code>. When a directory is specified instead of a file, the server checks whether there is a file <code>index.html</code> in this directory and serves it if available.</p><p>Visiting <code>http://localhost:8000/</code> makes your browser send a standard HTTP <code>GET</code> request to the server. The server, running a listener loop, receives this request, looks for <code>index.html</code> in the root folder, and serves it. After serving it, <code>LiveServer</code> adds this file to the list of watched files. That is, whenever this file changes, a callback is fired (see below). The HTML page may also contain references to style sheets or pictures, which are then requested by your browser as well. The server sends them to the browser, and also adds them to the list of watched files.</p><h4 id="But-what-about-the-live-reloading?"><a class="docs-heading-anchor" href="#But-what-about-the-live-reloading?">But what about the live reloading?</a><a id="But-what-about-the-live-reloading?-1"></a><a class="docs-heading-anchor-permalink" href="#But-what-about-the-live-reloading?" title="Permalink"></a></h4><p>Triggering a page refresh in the browser is achieved by a WebSocket connection. The WebSocket API, according to <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API">MDN</a>, is</p><blockquote><p>an advanced technology that makes it possible to open a two-way interactive communication session between the user&#39;s browser and a server.</p></blockquote><p><code>LiveServer</code> injects a small piece of JavaScript code into every HTML file before serving it. This snippet is executed by the browser and opens a WebSocket connection to the server, which in turn adds it to a list of viewers of this page.</p><p>The server can now send the message &quot;update&quot; to all viewers of a page whenever the page is changed. The code snippet reacts to this message by triggering a page reload. The update is triggered by the callback mentioned above. When the file is not an HTML file, the viewers of <em>any</em> HTML file are updated, since <code>LiveServer</code> currently does not keep track of which HTML files reference what other files.</p></article><nav class="docs-footer"><a class="docs-footer-nextpage" href="man/functionalities/">Functionalities »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Saturday 2 November 2024 00:40">Saturday 2 November 2024</span>. Using Julia version 1.9.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+    └── blah.html</code></pre><p>Calling <code>serve()</code> from within this directory starts a file server. It serves the contents of the directory as a static site, with the folder structure defining the paths of the URLs. That is, the file <code>blah.html</code> can be viewed at <code>/pages/blah.html</code>. When a directory is specified instead of a file, the server checks whether there is a file <code>index.html</code> in this directory and serves it if available.</p><p>Visiting <code>http://localhost:8000/</code> makes your browser send a standard HTTP <code>GET</code> request to the server. The server, running a listener loop, receives this request, looks for <code>index.html</code> in the root folder, and serves it. After serving it, <code>LiveServer</code> adds this file to the list of watched files. That is, whenever this file changes, a callback is fired (see below). The HTML page may also contain references to style sheets or pictures, which are then requested by your browser as well. The server sends them to the browser, and also adds them to the list of watched files.</p><h4 id="But-what-about-the-live-reloading?"><a class="docs-heading-anchor" href="#But-what-about-the-live-reloading?">But what about the live reloading?</a><a id="But-what-about-the-live-reloading?-1"></a><a class="docs-heading-anchor-permalink" href="#But-what-about-the-live-reloading?" title="Permalink"></a></h4><p>Triggering a page refresh in the browser is achieved by a WebSocket connection. The WebSocket API, according to <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API">MDN</a>, is</p><blockquote><p>an advanced technology that makes it possible to open a two-way interactive communication session between the user&#39;s browser and a server.</p></blockquote><p><code>LiveServer</code> injects a small piece of JavaScript code into every HTML file before serving it. This snippet is executed by the browser and opens a WebSocket connection to the server, which in turn adds it to a list of viewers of this page.</p><p>The server can now send the message &quot;update&quot; to all viewers of a page whenever the page is changed. The code snippet reacts to this message by triggering a page reload. The update is triggered by the callback mentioned above. When the file is not an HTML file, the viewers of <em>any</em> HTML file are updated, since <code>LiveServer</code> currently does not keep track of which HTML files reference what other files.</p></article><nav class="docs-footer"><a class="docs-footer-nextpage" href="man/functionalities/">Functionalities »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Saturday 2 November 2024 00:45">Saturday 2 November 2024</span>. Using Julia version 1.9.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

dev/man/extending_ls/index.html

@@ -17,4 +17,4 @@
         # cleanup ...
     end
     return nothing
-end</code></pre><p>That is, the <code>coreloopfun</code> is called roughly every 100 ms while the server is running. By default the <code>coreloopfun</code> does nothing.</p><p>An example where this mechanism could be used is when your code handles the processing of files from one format (say markdown) to HTML. You want the <code>FileWatcher</code> to trigger browser reloads whenever new versions of these HTML files are produced. However, at the same time, you want another process to keep track of the markdown files and re-process them as they change. You can hook this second watcher into the core loop of <code>LiveServer</code> using the <code>coreloopfun</code>. An example for this use case is <a href="https://github.com/tlienart/JuDoc.jl">JuDoc.jl</a>.</p><h2 id="Why-not-use-FileWatching?"><a class="docs-heading-anchor" href="#Why-not-use-FileWatching?">Why not use <code>FileWatching</code>?</a><a id="Why-not-use-FileWatching?-1"></a><a class="docs-heading-anchor-permalink" href="#Why-not-use-FileWatching?" title="Permalink"></a></h2><p>You may be aware of the <a href="https://docs.julialang.org/en/v1/stdlib/FileWatching/index.html"><code>FileWatching</code></a> module in <code>Base</code> and may wonder why we did not just use that one. The main reasons we decided not to use it are:</p><ul><li>it triggers <em>a lot</em>: where our system only triggers the callback function upon <em>saving</em> a file (e.g. you modified the file and saved the modification), <code>FileWatching</code> is more sensitive (for instance it will trigger when you <em>open</em> the file),</li><li>it is somewhat harder to make your own custom mechanisms to fire page reloads.</li></ul><p>So ultimately, our system can be seen as a poor man&#39;s implementation of <code>FileWatching</code> that is robust, simple and easy to customise.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../functionalities/">« Functionalities</a><a class="docs-footer-nextpage" href="../ls+lit/">LiveServer + Literate »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Saturday 2 November 2024 00:40">Saturday 2 November 2024</span>. Using Julia version 1.9.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+end</code></pre><p>That is, the <code>coreloopfun</code> is called roughly every 100 ms while the server is running. By default the <code>coreloopfun</code> does nothing.</p><p>An example where this mechanism could be used is when your code handles the processing of files from one format (say markdown) to HTML. You want the <code>FileWatcher</code> to trigger browser reloads whenever new versions of these HTML files are produced. However, at the same time, you want another process to keep track of the markdown files and re-process them as they change. You can hook this second watcher into the core loop of <code>LiveServer</code> using the <code>coreloopfun</code>. An example for this use case is <a href="https://github.com/tlienart/JuDoc.jl">JuDoc.jl</a>.</p><h2 id="Why-not-use-FileWatching?"><a class="docs-heading-anchor" href="#Why-not-use-FileWatching?">Why not use <code>FileWatching</code>?</a><a id="Why-not-use-FileWatching?-1"></a><a class="docs-heading-anchor-permalink" href="#Why-not-use-FileWatching?" title="Permalink"></a></h2><p>You may be aware of the <a href="https://docs.julialang.org/en/v1/stdlib/FileWatching/index.html"><code>FileWatching</code></a> module in <code>Base</code> and may wonder why we did not just use that one. The main reasons we decided not to use it are:</p><ul><li>it triggers <em>a lot</em>: where our system only triggers the callback function upon <em>saving</em> a file (e.g. you modified the file and saved the modification), <code>FileWatching</code> is more sensitive (for instance it will trigger when you <em>open</em> the file),</li><li>it is somewhat harder to make your own custom mechanisms to fire page reloads.</li></ul><p>So ultimately, our system can be seen as a poor man&#39;s implementation of <code>FileWatching</code> that is robust, simple and easy to customise.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../functionalities/">« Functionalities</a><a class="docs-footer-nextpage" href="../ls+lit/">LiveServer + Literate »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Saturday 2 November 2024 00:45">Saturday 2 November 2024</span>. Using Julia version 1.9.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

dev/man/functionalities/index.html

@@ -29,4 +29,4 @@
 ... Rest of configuration within your make.jl file
 
 =#</code></pre><ol><li>Finally the user should start the <code>LiveServer</code> session with an additional </li></ol><p>argument to watch the package <code>src/</code> folder for changes. This additional argument will force <code>LiveServer</code> to watch the <code>src/</code> folder for changes and re-render the documentation site once <code>LiveServer</code> notices a change.</p><pre><code class="language-julia hljs">using LiveServer
-servedocs(include_dirs=[&quot;src/&quot;])</code></pre><p>Once these change are completed, changes to a function&#39;s docstring will trigger a re-rendering of the documentation website in the user&#39;s browser.</p><h3 id="Additional-keywords"><a class="docs-heading-anchor" href="#Additional-keywords">Additional keywords</a><a id="Additional-keywords-1"></a><a class="docs-heading-anchor-permalink" href="#Additional-keywords" title="Permalink"></a></h3><p>The <code>servedocs</code> function now takes extra keywords which may, in some cases, make your life easier:</p><ul><li><code>foldername=&quot;docs&quot;</code>, is the name of folder that contains the documentation, which can be changed if it&#39;s different than <code>docs</code>.</li><li><code>doc_env=false</code>, if set to true, the <code>Project.toml</code> available in <code>docs/</code> will be activated (note 1),</li><li><code>skip_dir=&quot;&quot;</code>, indicates a directory to skip when looking at the docs folder for change, this can be useful when using packages like Literate or Weave that may generate files inside your <code>src</code> folder.</li></ul><p>Note that in latter two cases these keywords are there for your convenience but would be best not used. See also the discussion in <a href="https://github.com/asprionj/LiveServer.jl/issues/85">this issue</a>. In the first case, doing</p><pre><code class="nohighlight hljs">julia --project=docs -e &#39;using LiveServer; servedocs()&#39;</code></pre><p>is more robust.</p><p>In the second case, it would be best if you made sure  that  all generated files are saved in <code>docs/build/...</code>.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../../">« Home</a><a class="docs-footer-nextpage" href="../extending_ls/">Extending LiveServer »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Saturday 2 November 2024 00:39">Saturday 2 November 2024</span>. Using Julia version 1.9.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+servedocs(include_dirs=[&quot;src/&quot;])</code></pre><p>Once these change are completed, changes to a function&#39;s docstring will trigger a re-rendering of the documentation website in the user&#39;s browser.</p><h3 id="Additional-keywords"><a class="docs-heading-anchor" href="#Additional-keywords">Additional keywords</a><a id="Additional-keywords-1"></a><a class="docs-heading-anchor-permalink" href="#Additional-keywords" title="Permalink"></a></h3><p>The <code>servedocs</code> function now takes extra keywords which may, in some cases, make your life easier:</p><ul><li><code>foldername=&quot;docs&quot;</code>, is the name of folder that contains the documentation, which can be changed if it&#39;s different than <code>docs</code>.</li><li><code>doc_env=false</code>, if set to true, the <code>Project.toml</code> available in <code>docs/</code> will be activated (note 1),</li><li><code>skip_dir=&quot;&quot;</code>, indicates a directory to skip when looking at the docs folder for change, this can be useful when using packages like Literate or Weave that may generate files inside your <code>src</code> folder.</li></ul><p>Note that in latter two cases these keywords are there for your convenience but would be best not used. See also the discussion in <a href="https://github.com/asprionj/LiveServer.jl/issues/85">this issue</a>. In the first case, doing</p><pre><code class="nohighlight hljs">julia --project=docs -e &#39;using LiveServer; servedocs()&#39;</code></pre><p>is more robust.</p><p>In the second case, it would be best if you made sure  that  all generated files are saved in <code>docs/build/...</code>.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../../">« Home</a><a class="docs-footer-nextpage" href="../extending_ls/">Extending LiveServer »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Saturday 2 November 2024 00:45">Saturday 2 November 2024</span>. Using Julia version 1.9.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>