Skip to content

Commit

Permalink
build based on 6908f05
Browse files Browse the repository at this point in the history
  • Loading branch information
Documenter.jl committed May 30, 2024
1 parent 460315d commit e577eab
Show file tree
Hide file tree
Showing 18 changed files with 1,254 additions and 0 deletions.
1 change: 1 addition & 0 deletions previews/PR178/.documenter-siteinfo.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"documenter":{"julia_version":"1.10.3","generation_timestamp":"2024-05-30T07:41:56","documenter_version":"1.4.1"}}
11 changes: 11 additions & 0 deletions previews/PR178/10-full-guide/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
<!DOCTYPE html>
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Full Guide · COPIERTemplate.jl</title><meta name="title" content="Full Guide · COPIERTemplate.jl"/><meta property="og:title" content="Full Guide · COPIERTemplate.jl"/><meta property="twitter:title" content="Full Guide · COPIERTemplate.jl"/><meta name="description" content="Documentation for COPIERTemplate.jl."/><meta property="og:description" content="Documentation for COPIERTemplate.jl."/><meta property="twitter:description" content="Documentation for COPIERTemplate.jl."/><meta property="og:url" content="https://abelsiqueira.github.io/COPIERTemplate.jl/10-full-guide/"/><meta property="twitter:url" content="https://abelsiqueira.github.io/COPIERTemplate.jl/10-full-guide/"/><link rel="canonical" href="https://abelsiqueira.github.io/COPIERTemplate.jl/10-full-guide/"/><script data-outdated-warner src="../assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.050/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../assets/documenter.js"></script><script src="../search_index.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../assets/themeswap.js"></script><link href="../assets/style.css" rel="stylesheet" type="text/css"/></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="../"><img src="../assets/logo.png" alt="COPIERTemplate.jl logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="../">COPIERTemplate.jl</a></span></div><button class="docs-search-query input is-rounded is-small is-clickable my-2 mx-auto py-1 px-2" id="documenter-search-query">Search docs (Ctrl + /)</button><ul class="docs-menu"><li><a class="tocitem" href="../">Home</a></li><li class="is-active"><a class="tocitem" href>Full Guide</a><ul class="internal"><li><a class="tocitem" href="#Before-installing"><span>Before installing</span></a></li><li><a class="tocitem" href="#Installation"><span>Installation</span></a></li><li><a class="tocitem" href="#Post-installation"><span>Post-installation</span></a></li></ul></li><li><a class="tocitem" href="../20-explanation/">Explanation</a></li><li><a class="tocitem" href="../90-contributing/">Contributing</a></li><li><a class="tocitem" href="../90-developer/">Developer docs</a></li><li><a class="tocitem" href="../90-reference/">Reference</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><a class="docs-sidebar-button docs-navbar-link fa-solid fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href>Full Guide</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Full Guide</a></li></ul></nav><div class="docs-right"><a class="docs-navbar-link" href="https://github.com/abelsiqueira/COPIERTemplate.jl/blob/main/docs/src/10-full-guide.md#" title="Edit source on GitHub"><span class="docs-icon fa-solid"></span></a><a class="docs-settings-button docs-navbar-link fa-solid fa-gear" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-article-toggle-button fa-solid fa-chevron-up" id="documenter-article-toggle-button" href="javascript:;" title="Collapse all docstrings"></a></div></header><article class="content" id="documenter-page"><h1 id="full_guide"><a class="docs-heading-anchor" href="#full_guide">Full guide</a><a id="full_guide-1"></a><a class="docs-heading-anchor-permalink" href="#full_guide" title="Permalink"></a></h1><p>Welcome to <strong>full usage guide</strong> of COPIERTemplate.</p><h2 id="Before-installing"><a class="docs-heading-anchor" href="#Before-installing">Before installing</a><a id="Before-installing-1"></a><a class="docs-heading-anchor-permalink" href="#Before-installing" title="Permalink"></a></h2><ol><li>We highly recommend that you install <a href="https://pre-commit.com"><code>pre-commit</code></a>. Our whole linting is based on that tool, so you might want to adopt it locally.</li><li>Decide if you are going to install <code>copier</code> or use our Julia interface.</li><li>If you use <code>copier</code> directly, find a UUID version 4 generator.<ul><li>On Linux and MacOS, you can run <code>uuidgen</code></li><li>On Julia, you can run <code>using UUIDs; uuid4()</code></li><li>Online, you can try <a href="https://www.uuidgenerator.net/version4">uuidgenerator.net</a></li></ul></li></ol><h2 id="Installation"><a class="docs-heading-anchor" href="#Installation">Installation</a><a id="Installation-1"></a><a class="docs-heading-anchor-permalink" href="#Installation" title="Permalink"></a></h2><p>To install with COPIERTemplate.jl, install the package, use it, and run <code>COPIERTemplate.generate(path)</code>.</p><p>Alternatively, this can also be installed directly via <a href="https://copier.readthedocs.io">copier</a>, with the command</p><pre><code class="language-bash hljs">copier copy https://github.com/abelsiqueira/COPIERTemplate.jl YourPackage.jl</code></pre><p>Many questions will be asked. The explanation on them should be sufficient (if they aren&#39;t, please let us know).</p><h2 id="Post-installation"><a class="docs-heading-anchor" href="#Post-installation">Post-installation</a><a id="Post-installation-1"></a><a class="docs-heading-anchor-permalink" href="#Post-installation" title="Permalink"></a></h2><h3 id="Add-to-GitHub"><a class="docs-heading-anchor" href="#Add-to-GitHub">Add to GitHub</a><a id="Add-to-GitHub-1"></a><a class="docs-heading-anchor-permalink" href="#Add-to-GitHub" title="Permalink"></a></h3><p>The resulting folder will not be a <code>git</code> package yet (to avoid trust issues), so you need to handle that yourself. Here is a short example:</p><pre><code class="language-bash hljs">cd YourPackage.jl
git init
git add .
pre-commit run -a # Try to fix possible pre-commit issues (failures are expected)
git add .
git commit -m &quot;First commit&quot;
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="Thursday 30 May 2024 07:41">Thursday 30 May 2024</span>. Using Julia version 1.10.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
2 changes: 2 additions & 0 deletions previews/PR178/20-explanation/index.html
View file

Large diffs are not rendered by default.

Loading

0 comments on commit e577eab

Please sign in to comment.