build based on 68a8016

dev/.documenter-siteinfo.json

@@ -1 +1 @@
-{"documenter":{"julia_version":"1.10.3","generation_timestamp":"2024-05-17T09:59:27","documenter_version":"1.4.1"}}
+{"documenter":{"julia_version":"1.10.3","generation_timestamp":"2024-05-17T12:42:55","documenter_version":"1.4.1"}}

dev/10-full-guide/index.html

@@ -8,4 +8,4 @@
 pre-commit install # Future commits can&#39;t be directly to main unless you use -n</code></pre><p>It is common to have some pre-commit issues due to your package&#39;s name length triggering JuliaFormatter.</p><p>Create a repo on GitHub and push your code to it.</p><div class="admonition is-info"><header class="admonition-header">Info</header><div class="admonition-body"><p>The actions will run and you will see errors in the documentation and linting. Do not despair.</p></div></div><h3 id="Documentation"><a class="docs-heading-anchor" href="#Documentation">Documentation</a><a id="Documentation-1"></a><a class="docs-heading-anchor-permalink" href="#Documentation" title="Permalink"></a></h3><p>Go to your package setting on Github and find the &quot;Actions&quot; tab, the &quot;General&quot; link. On that page, find the &quot;Workflow permissions&quot; and change the selection to &quot;Read and write permissions&quot;, and enable &quot;Allow GitHub Actions can create and approve pull requests&quot;. This will allow the documentation workflow to work for development.</p><p>Go to the Actions page, click the failing Docs workflow and click on &quot;re-run all jobs&quot;. It should pass now.</p><p>Now, go to your package setting on GitHub and find the &quot;Pages&quot; link. You should see an option to set the <strong>Source</strong> to &quot;Deploy from a branch&quot;, and select the branch to be &quot;gh-pages&quot; and to deploy from the &quot;/ (root)&quot;.</p><p>After circa 1 minute, you can check that the documentation was built properly.</p><div class="admonition is-info"><header class="admonition-header">Info</header><div class="admonition-body"><p>At this point, you should have passing workflows.</p><ol><li>Tests should have been passing from the start.</li><li>Lint was fixed when we pushed the code to GitHub.</li><li>Docs was fixed with the permissions change.</li></ol></div></div><p>You will still need to set a <code>DOCUMENTER_KEY</code> to build the documentation from the tags automatically when using TagBot (which we do by default). Do the following:</p><pre><code class="language-bash hljs">pkg&gt; activate --temp
 pkg&gt; add DocumenterTools
 julia&gt; using DocumenterTools
-julia&gt; DocumenterTools.genkeys(user=&quot;UserName&quot;, repo=&quot;PackageName.jl&quot;)</code></pre><p>Follow the instruction in the terminal.</p><h3 id="Add-key-for-Copier.yml-workflow-(or-delete-it)"><a class="docs-heading-anchor" href="#Add-key-for-Copier.yml-workflow-(or-delete-it)">Add key for Copier.yml workflow (or delete it)</a><a id="Add-key-for-Copier.yml-workflow-(or-delete-it)-1"></a><a class="docs-heading-anchor-permalink" href="#Add-key-for-Copier.yml-workflow-(or-delete-it)" title="Permalink"></a></h3><p>You can reapply the template in the future. This is normally a manual job, specially because normally there are conflicts. That being said, we are experimenting with having a workflow that automatically checks whether there are updates to the template and reapplies it. A Pull Request is created with the result.</p><div class="admonition is-warning"><header class="admonition-header">Warning</header><div class="admonition-body"><p>This is optional, and in development, so you might want to delete the workflow instead.</p></div></div><p>If you decide to use, here are the steps to set it up:</p><ol><li>Create a Personal Access Token to be used by the Copier workflow.</li><li>Go to <a href="https://github.com/settings/tokens">https://github.com/settings/tokens</a>.</li><li>Create a token with &quot;Content&quot;, &quot;Pull-request&quot;, and &quot;Workflows&quot; permissions.</li><li>Copy the Token.</li><li>Go to your <code>YOUR_PACKAGE_URL/settings/secrets/actions</code>.</li><li>Create a &quot;New repository secret&quot; named <code>COPIER_PAT</code>.</li></ol><h3 id="CITATION.cff-and-Zenodo-deposition"><a class="docs-heading-anchor" href="#CITATION.cff-and-Zenodo-deposition">CITATION.cff and Zenodo deposition</a><a id="CITATION.cff-and-Zenodo-deposition-1"></a><a class="docs-heading-anchor-permalink" href="#CITATION.cff-and-Zenodo-deposition" title="Permalink"></a></h3><p>Update your <code>CITATION.cff</code> file with correct information. You can use <a href="https://citation-file-format.github.io/cff-initializer-javascript/#/">cffinit</a> to generate it easily.</p><p>Before releasing, enable Zenodo integration at <a href="https://zenodo.org/account/settings/github/">https://zenodo.org/account/settings/github/</a> to automatically generate a deposition of your package, i.e., archive a version on Zenodo and generate a DOI.</p><h3 id="Update-README.md"><a class="docs-heading-anchor" href="#Update-README.md">Update README.md</a><a id="Update-README.md-1"></a><a class="docs-heading-anchor-permalink" href="#Update-README.md" title="Permalink"></a></h3><ol><li>Update the badges</li><li>Add a description</li></ol><h3 id="Enable-discussions"><a class="docs-heading-anchor" href="#Enable-discussions">Enable discussions</a><a id="Enable-discussions-1"></a><a class="docs-heading-anchor-permalink" href="#Enable-discussions" title="Permalink"></a></h3><p>Enable GitHub discussions.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../">« Home</a><a class="docs-footer-nextpage" href="../20-explanation/">Explanation »</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="auto">Automatic (OS)</option><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 1.4.1 on <span class="colophon-date" title="Friday 17 May 2024 09:59">Friday 17 May 2024</span>. Using Julia version 1.10.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+julia&gt; DocumenterTools.genkeys(user=&quot;UserName&quot;, repo=&quot;PackageName.jl&quot;)</code></pre><p>Follow the instruction in the terminal.</p><h3 id="Add-key-for-Copier.yml-workflow-(or-delete-it)"><a class="docs-heading-anchor" href="#Add-key-for-Copier.yml-workflow-(or-delete-it)">Add key for Copier.yml workflow (or delete it)</a><a id="Add-key-for-Copier.yml-workflow-(or-delete-it)-1"></a><a class="docs-heading-anchor-permalink" href="#Add-key-for-Copier.yml-workflow-(or-delete-it)" title="Permalink"></a></h3><p>You can reapply the template in the future. This is normally a manual job, specially because normally there are conflicts. That being said, we are experimenting with having a workflow that automatically checks whether there are updates to the template and reapplies it. A Pull Request is created with the result.</p><div class="admonition is-warning"><header class="admonition-header">Warning</header><div class="admonition-body"><p>This is optional, and in development, so you might want to delete the workflow instead.</p></div></div><p>If you decide to use, here are the steps to set it up:</p><ol><li>Create a Personal Access Token to be used by the Copier workflow.</li><li>Go to <a href="https://github.com/settings/tokens">https://github.com/settings/tokens</a>.</li><li>Create a token with &quot;Content&quot;, &quot;Pull-request&quot;, and &quot;Workflows&quot; permissions.</li><li>Copy the Token.</li><li>Go to your <code>YOUR_PACKAGE_URL/settings/secrets/actions</code>.</li><li>Create a &quot;New repository secret&quot; named <code>COPIER_PAT</code>.</li></ol><h3 id="CITATION.cff-and-Zenodo-deposition"><a class="docs-heading-anchor" href="#CITATION.cff-and-Zenodo-deposition">CITATION.cff and Zenodo deposition</a><a id="CITATION.cff-and-Zenodo-deposition-1"></a><a class="docs-heading-anchor-permalink" href="#CITATION.cff-and-Zenodo-deposition" title="Permalink"></a></h3><p>Update your <code>CITATION.cff</code> file with correct information. You can use <a href="https://citation-file-format.github.io/cff-initializer-javascript/#/">cffinit</a> to generate it easily.</p><p>Before releasing, enable Zenodo integration at <a href="https://zenodo.org/account/settings/github/">https://zenodo.org/account/settings/github/</a> to automatically generate a deposition of your package, i.e., archive a version on Zenodo and generate a DOI.</p><h3 id="Update-README.md"><a class="docs-heading-anchor" href="#Update-README.md">Update README.md</a><a id="Update-README.md-1"></a><a class="docs-heading-anchor-permalink" href="#Update-README.md" title="Permalink"></a></h3><ol><li>Update the badges</li><li>Add a description</li></ol><h3 id="Enable-discussions"><a class="docs-heading-anchor" href="#Enable-discussions">Enable discussions</a><a id="Enable-discussions-1"></a><a class="docs-heading-anchor-permalink" href="#Enable-discussions" title="Permalink"></a></h3><p>Enable GitHub discussions.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../">« Home</a><a class="docs-footer-nextpage" href="../20-explanation/">Explanation »</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="auto">Automatic (OS)</option><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 1.4.1 on <span class="colophon-date" title="Friday 17 May 2024 12:42">Friday 17 May 2024</span>. Using Julia version 1.10.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>