Update README and docs generation (#19)

ITensor · Nov 23, 2024 · 9c6639c · 9c6639c
1 parent 5fc0669
commit 9c6639c
Show file tree

Hide file tree

Showing 27 changed files with 166 additions and 148 deletions.
diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/.github/ISSUE_TEMPLATE/BUG_REPORT.md
@@ -22,6 +22,7 @@ If you are unable to construct a minimal code that demonstrates the bug or unexp
 ```julia
 [YOUR MINIMAL RUNNABLE CODE HERE]
 ```
+
 </p></details>
 
 

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -11,13 +11,15 @@ If practical and applicable, please include a minimal demonstration of the previ
 ```julia
 [YOUR MINIMAL DEMONSTRATION OF PREVIOUS BEHAVIOR]
 ```
+
 </p></details>
 
 <details><summary>Minimal demonstration of new behavior</summary><p>
 
 ```julia
 [YOUR MINIMAL DEMONSTRATION OF NEW BEHAVIOR]
 ```
+
 </p></details>
 
 # How Has This Been Tested?

diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -23,8 +23,8 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.10'
           - 'lts'
+          - '1'
         os:
           - ubuntu-latest
           - macOS-latest

diff --git a/.github/workflows/LiterateCheck.yml b/.github/workflows/LiterateCheck.yml
@@ -16,16 +16,20 @@ jobs:
           version: 1
       - name: Install Literate and generate docs
         run: |
-          julia  -e 'using Pkg; Pkg.add(PackageSpec(name="Literate"))'
-          julia  -e 'using Literate; Literate.markdown("examples/README.jl", "docs/src"; flavor=Literate.DocumenterFlavor(), name="index")'
+          julia  -e '
+          using Pkg
+          Pkg.develop(PackageSpec(path=pwd()))
+          Pkg.instantiate()
+          Pkg.add(PackageSpec(name="Literate"))'
+          julia  -e 'include("make_readme.jl")'
       - name: Check if docs need to be updated
         run: |
           julia -e '
           out = Cmd(`git diff --name-only`) |> read |> String
           if out == ""
               exit(0)
           else
-              @error "The documentation is outdated, rerun Literate to regenerate them."
+              @error "The docs are outdated, rerun Literate to regenerate them."
               write(stdout, out)
               out_diff = Cmd(`git diff`) |> read |> String
               @error "Diff:"

diff --git a/.gitignore b/.gitignore
@@ -9,6 +9,7 @@
 .vscode/
 /docs/Manifest.toml
 /docs/build/
+/docs/src/index.md
 Manifest.toml
 benchmark/*.json
 docs/build/

diff --git a/Project.toml b/Project.toml
@@ -6,13 +6,15 @@ version = "0.1.0"
 [deps]
 Git = "d7ba0133-e1db-5d97-8f8c-041e4b3a1eb2"
 Git_jll = "f8c6e375-362e-5223-8a59-34ff63f689eb"
+LibGit2 = "76f85450-5226-5b5a-8eaa-529ad045b433"
 PkgSkeleton = "d254efa0-af53-535e-b7f1-03c1c9fbcbe7"
 Preferences = "21216c6a-2e73-6563-6e65-726566657250"
 
 [compat]
 Aqua = "0.8.9"
 Git = "1.3.1"
 Git_jll = "2.46.2"
+LibGit2 = "1.10"
 PkgSkeleton = "1.3.1"
 Preferences = "1.4.3"
 Test = "1.10"

diff --git a/README.md b/README.md
diff --git a/README.md b/README.md
@@ -0,0 +1,40 @@
+# ITensorPkgSkeleton.jl
+
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://ITensor.github.io/ITensorPkgSkeleton.jl/stable/)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://ITensor.github.io/ITensorPkgSkeleton.jl/dev/)
+[![Build Status](https://github.com/ITensor/ITensorPkgSkeleton.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/ITensor/ITensorPkgSkeleton.jl/actions/workflows/CI.yml?query=branch%3Amain)
+[![Coverage](https://codecov.io/gh/ITensor/ITensorPkgSkeleton.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/ITensor/ITensorPkgSkeleton.jl)
+[![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
+[![Aqua](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
+
+## Installation instructions
+
+```julia
+julia> using Pkg: Pkg
+
+julia> Pkg.add("https://github.com/ITensor/ITensorPkgSkeleton.jl")
+```
+
+## Examples
+
+````julia
+using ITensorPkgSkeleton: ITensorPkgSkeleton
+````
+
+This step might be required to circumvent issues with
+the version of git installed by `Git.jl`.
+
+````julia
+ITensorPkgSkeleton.use_system_git!()
+````
+
+If `path` isn't specified, it defaults to `~/.julia/dev`.
+
+````julia
+ITensorPkgSkeleton.generate("NewPkg"; path=mktempdir())
+````
+
+---
+
+*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*
+
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -2,3 +2,4 @@
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Git_jll = "f8c6e375-362e-5223-8a59-34ff63f689eb"
 ITensorPkgSkeleton = "3d388ab1-018a-49f4-ae50-18094d5f71ea"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,10 +1,12 @@
-using ITensorPkgSkeleton
-using Documenter
+using ITensorPkgSkeleton: ITensorPkgSkeleton
+using Documenter: Documenter, DocMeta, deploydocs, makedocs
 
 DocMeta.setdocmeta!(
   ITensorPkgSkeleton, :DocTestSetup, :(using ITensorPkgSkeleton); recursive=true
 )
 
+include("make_index.jl")
+
 makedocs(;
   modules=[ITensorPkgSkeleton],
   authors="ITensor developers <[email protected]> and contributors",

diff --git a/docs/make_index.jl b/docs/make_index.jl
@@ -0,0 +1,9 @@
+using Literate: Literate
+using ITensorPkgSkeleton: ITensorPkgSkeleton
+
+Literate.markdown(
+  joinpath(pkgdir(ITensorPkgSkeleton), "examples", "README.jl"),
+  joinpath(pkgdir(ITensorPkgSkeleton), "docs", "src");
+  flavor=Literate.DocumenterFlavor(),
+  name="index",
+)
diff --git a/docs/src/index.md b/docs/src/index.md
diff --git a/examples/README.jl b/examples/README.jl
@@ -25,17 +25,3 @@ using ITensorPkgSkeleton: ITensorPkgSkeleton
 ITensorPkgSkeleton.use_system_git!()
 # If `path` isn't specified, it defaults to `~/.julia/dev`.
 ITensorPkgSkeleton.generate("NewPkg"; path=mktempdir())
-
-# You can generate this README with:
-#=
-```julia
-using Literate: Literate
-using ITensorPkgSkeleton: ITensorPkgSkeleton
-Literate.markdown(
-  joinpath(pkgdir(ITensorPkgSkeleton), "examples", "README.jl"),
-  joinpath(pkgdir(ITensorPkgSkeleton), "docs", "src");
-  flavor=Literate.DocumenterFlavor(),
-  name="index",
-)
-```
-=#
diff --git a/make_readme.jl b/make_readme.jl
@@ -0,0 +1,9 @@
+using Literate: Literate
+using ITensorPkgSkeleton: ITensorPkgSkeleton
+
+Literate.markdown(
+  joinpath(pkgdir(ITensorPkgSkeleton), "examples", "README.jl"),
+  joinpath(pkgdir(ITensorPkgSkeleton));
+  flavor=Literate.CommonMarkFlavor(),
+  name="README",
+)
diff --git a/src/ITensorPkgSkeleton.jl b/src/ITensorPkgSkeleton.jl
@@ -1,6 +1,7 @@
 module ITensorPkgSkeleton
 
 using Git: git
+using LibGit2: LibGit2
 using PkgSkeleton: PkgSkeleton
 using Preferences: Preferences
 
@@ -93,6 +94,15 @@ function set_default_template_path(template)
   return joinpath(pkgdir(ITensorPkgSkeleton), "templates", template)
 end
 
+function is_git_repo(path)
+  return try
+    LibGit2.GitRepo(path)
+    return true
+  catch
+    return false
+  end
+end
+
 function generate(
   pkg_name; path=default_path(), templates=default_templates(), user_replacements=(;)
 )
@@ -103,11 +113,14 @@ function generate(
   # Process downstream package information.
   user_replacements = format_downstream_pkgs(user_replacements)
   pkg_path = joinpath(path, pkg_name)
+  is_new_repo = !is_git_repo(pkg_path)
   branch_name = default_branch_name()
   user_replacements_dict = Dict(keys(user_replacements) .=> values(user_replacements))
   PkgSkeleton.generate(pkg_path; templates, user_replacements=user_replacements_dict)
-  # Change the default branch.
-  change_branch_name(pkg_path, branch_name)
+  if is_new_repo
+    # Change the default branch if this is a new repository.
+    change_branch_name(pkg_path, branch_name)
+  end
   return nothing
 end
 

diff --git a/templates/default/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/templates/default/.github/ISSUE_TEMPLATE/BUG_REPORT.md
@@ -22,6 +22,7 @@ If you are unable to construct a minimal code that demonstrates the bug or unexp
 ```julia
 [YOUR MINIMAL RUNNABLE CODE HERE]
 ```
+
 </p></details>
 
 

diff --git a/templates/default/.github/PULL_REQUEST_TEMPLATE.md b/templates/default/.github/PULL_REQUEST_TEMPLATE.md
@@ -11,13 +11,15 @@ If practical and applicable, please include a minimal demonstration of the previ
 ```julia
 [YOUR MINIMAL DEMONSTRATION OF PREVIOUS BEHAVIOR]
 ```
+
 </p></details>
 
 <details><summary>Minimal demonstration of new behavior</summary><p>
 
 ```julia
 [YOUR MINIMAL DEMONSTRATION OF NEW BEHAVIOR]
 ```
+
 </p></details>
 
 # How Has This Been Tested?

diff --git a/templates/default/.github/workflows/CI.yml b/templates/default/.github/workflows/CI.yml
@@ -23,8 +23,8 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.10'
           - 'lts'
+          - '1'
         os:
           - ubuntu-latest
           - macOS-latest

diff --git a/templates/default/.github/workflows/LiterateCheck.yml b/templates/default/.github/workflows/LiterateCheck.yml
@@ -16,16 +16,20 @@ jobs:
           version: 1
       - name: Install Literate and generate docs
         run: |
-          julia  -e 'using Pkg; Pkg.add(PackageSpec(name="Literate"))'
-          julia  -e 'using Literate; Literate.markdown("examples/README.jl", "docs/src"; flavor=Literate.DocumenterFlavor(), name="index")'
+          julia  -e '
+          using Pkg
+          Pkg.develop(PackageSpec(path=pwd()))
+          Pkg.instantiate()
+          Pkg.add(PackageSpec(name="Literate"))'
+          julia  -e 'include("make_readme.jl")'
       - name: Check if docs need to be updated
         run: |
           julia -e '
           out = Cmd(`git diff --name-only`) |> read |> String
           if out == ""
               exit(0)
           else
-              @error "The documentation is outdated, rerun Literate to regenerate them."
+              @error "The docs are outdated, rerun Literate to regenerate them."
               write(stdout, out)
               out_diff = Cmd(`git diff`) |> read |> String
               @error "Diff:"

diff --git a/templates/default/.gitignore b/templates/default/.gitignore
@@ -9,6 +9,8 @@
 .vscode/
 /docs/Manifest.toml
 /docs/build/
+/docs/src/index.md
 Manifest.toml
 benchmark/*.json
 docs/build/
+test/LocalPreferences.toml
diff --git a/templates/default/README.md b/templates/default/README.md
diff --git a/templates/default/README.md b/templates/default/README.md
@@ -0,0 +1,29 @@
+# {PKGNAME}.jl
+
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://ITensor.github.io/{PKGNAME}.jl/stable/)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://ITensor.github.io/{PKGNAME}.jl/dev/)
+[![Build Status](https://github.com/ITensor/{PKGNAME}.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/ITensor/{PKGNAME}.jl/actions/workflows/CI.yml?query=branch%3Amain)
+[![Coverage](https://codecov.io/gh/ITensor/{PKGNAME}.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/ITensor/{PKGNAME}.jl)
+[![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
+[![Aqua](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
+
+## Installation instructions
+
+```julia
+julia> using Pkg: Pkg
+
+julia> Pkg.add("https://github.com/ITensor/{PKGNAME}.jl")
+```
+
+## Examples
+
+````julia
+using {PKGNAME}: {PKGNAME}
+````
+
+Examples go here.
+
+---
+
+*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*
+
diff --git a/templates/default/docs/Project.toml b/templates/default/docs/Project.toml
@@ -1,3 +1,5 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-{PKGNAME} = "70ffe8f8-8519-465d-b12c-3b7d28f4e5e2"
+Git_jll = "f8c6e375-362e-5223-8a59-34ff63f689eb"
+{PKGNAME} = "3d388ab1-018a-49f4-ae50-18094d5f71ea"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
-Original file line number
+Diff line change
@@ Expand Up @@
     ```julia
     [YOUR MINIMAL RUNNABLE CODE HERE]
     ```
     </p></details>
@@ Expand Down @@