Clean up documentation (#423)

* Add precommit

* literate cleanup

* Update welcome

* Add markdown to formatter and run, fix hyperlinks

* Add interlinks and prettyurls

* Add PSY extref hyperlinks

* Add hyperlinks

* Add PSCB to interlinks and hyperlinks to tutorials

* Update modeler guide refs

* Fix old nrel-sienna links

* Remove contributed by

* Remove excess lines

* Fix nrel link

* Add basic missing docstrings

Author: kdayday

.github/workflows/doc-preview-cleanup.yml

@@ -0,0 +1,35 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time
+concurrency:
+  group: doc-preview-cleanup
+  cancel-in-progress: false
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.head.repo.fork == false
+    # This workflow pushes to gh-pages; permissions are per-job and independent of docs.yml
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+          if [ -d "${preview_dir}" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "documenter@juliadocs.github.io"
+              git rm -rf "${preview_dir}"
+              git commit -m "delete preview"
+              git branch gh-pages-new "$(echo "delete history" | git commit-tree "HEAD^{tree}")"
+              git push --force origin gh-pages-new:gh-pages
+          fi
+        env:
+          preview_dir: previews/PR${{ github.event.number }}

.github/workflows/docs.yml

@@ -18,6 +18,16 @@ jobs:
           version: 1
       - name: Install dependencies
         run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+
+      - name: Set DOCUMENTER_CURRENT_VERSION for tutorial download links
+        run: |
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            echo "DOCUMENTER_CURRENT_VERSION=previews/PR${{ github.event.pull_request.number }}" >> "$GITHUB_ENV"
+          elif [[ "${{ github.ref }}" == refs/tags/* ]]; then
+            echo "DOCUMENTER_CURRENT_VERSION=${GITHUB_REF_NAME}" >> "$GITHUB_ENV"
+          elif [[ "${{ github.ref }}" == "refs/heads/main" ]] || [[ "${{ github.ref }}" =~ ^refs/heads/release- ]]; then
+            echo "DOCUMENTER_CURRENT_VERSION=dev" >> "$GITHUB_ENV"
+          fi
       - name: Build and deploy
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: local
+    hooks:
+      - id: julia-formatter
+        name: Run Julia formatter
+        entry: julia scripts/formatter/formatter_code.jl
+        language: system
+        types: [file]
+        pass_filenames: false

docs/Project.toml

@@ -2,6 +2,7 @@
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"

docs/make.jl

@@ -1,14 +1,22 @@
 using Documenter, PowerSystems, DocStringExtensions, PowerSimulationsDynamics
-
-const _DOCS_BASE_URL = "https://sienna-platform.github.io/PowerSimulationsDynamics.jl/stable"
+using DocumenterInterLinks
 
 include(joinpath(@__DIR__, "make_tutorials.jl"))
 make_tutorials()
 
+links = InterLinks(
+    "PowerSystems" => "https://sienna-platform.github.io/PowerSystems.jl/stable/",
+    "PowerSystemCaseBuilder" => "https://sienna-platform.github.io/PowerSystemCaseBuilder.jl/stable/",
+)
+
 makedocs(;
     modules = [PowerSimulationsDynamics],
-    format = Documenter.HTML(; mathengine = Documenter.MathJax()),
+    format = Documenter.HTML(;
+        prettyurls = haskey(ENV, "GITHUB_ACTIONS"),
+        mathengine = Documenter.MathJax(),
+    ),
     sitename = "PowerSimulationsDynamics.jl",
+    plugins = [links],
     pages = Any[
         "Welcome Page" => "index.md",
         "Quick Start Guide" => "tutorials/generated_quick_start_guide.md",