Merge pull request #82 from Electa-Git/fix-docs

Fix docs

.github/workflows/documentation.yml

@@ -1,26 +1,26 @@
 name: Documentation
+
 on:
   push:
-    branches: [master]
+    branches:
+      - master
     tags: '*'
   pull_request:
-    types: [opened, synchronize, reopened]
-  schedule: 
-    - cron:  '0,5,10 13 * * *'
+
 jobs:
-  docs:
-    if: "!contains(github.event.head_commit.message, 'skip ci')"
-    name: Documentation
+  build:
+    permissions:
+      contents: write
+      statuses: write
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/setup-julia@latest
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
         with:
           version: '1'
-      - name: Install Dependencies
-        run: julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
-      - name: Build and Deploy
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
-        run: julia --project=docs docs/make.jl
+        run: julia --project=docs/ docs/make.jl

README.md

@@ -10,7 +10,7 @@ PowerModelsACDC.jl is a Julia/JuMP/PowerModels package with models for DC lines,
 Building upon the PowerModels architecture, the code is engineered to decouple problem specifications (e.g. Power Flow, Optimal Power Flow, ...) from the power network formulations (e.g. AC, DC-approximation, SOC-relaxation, ...).
 
 **Installation**
-The latest stable release of PowerModelACDC can be installed using the Julia package manager with
+The latest stable release of PowerModelsACDC can be installed using the Julia package manager with
 
 ```julia
 Pkg.add("PowerModelsACDC")
@@ -89,7 +89,7 @@ month={July},}
    ISSN = {1751-8687},
    title = {TNEP of meshed HVDC grids: ‘AC’, ‘DC’ and convex formulations},
    journal = {IET Generation, Transmission & Distribution},
-   issue = {24},   
+   issue = {24},
    volume = {13},
    year = {2019},
    month = {December},

docs/README.md

@@ -1,21 +1,36 @@
-# Building the Documentation for PowerModels.jl
+# Documentation for PowerModelsACDC.jl
 
-## Installation
-We rely on [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl). To install it, run the following command in a julia session:
+You can read this documentation online at
+<https://electa-git.github.io/PowerModelsACDC.jl/dev/>.
 
-```julia
-Pkg.add("Documenter")
-```
+## Preview the documentation (for developers)
 
-## Building the Docs
-To preview the html output of the documents, run the following command:
+While developing PowerModelsACDC.jl, you can preview the documentation locally in your
+browser with live-reload capability.
+In other words, when you modify a file, every browser tab that is currently displaying the
+corresponding page is automatically refreshed.
 
-```julia
-julia --color=yes make.jl
-```
+### Instructions for *nix
 
-You can then view the documents in `build/index.html`.
+1. Copy the following zsh/Julia code snippet:
 
-**Warning**: Do not `git commit` the contents of build (or any other content generated by Documenter) to your repository's master branch. This helps to avoid including unnessesary changes for anyone reviewing commits that happen to include documentation changes.
+   ```julia
+   #!/bin/zsh
+   #= # The following line is zsh code
+   julia -i $0:a # The string `$0:a` represents this file in zsh
+   =# # Following lines are Julia code
+   import Pkg
+   Pkg.activate(; temp=true)
+   Pkg.develop("PowerModelsACDC")
+   Pkg.add("Documenter")
+   Pkg.add("LiveServer")
+   using PowerModelsACDC, LiveServer
+   cd(dirname(dirname(pathof(PowerModelsACDC))))
+   servedocs()
+   exit()
+   ```
 
-For further details, please read the [documentation for Documenter.jl](https://juliadocs.github.io/Documenter.jl/stable/).
+2. Save it as a zsh script (name it like `preview_powermodelsacdc_docs.sh`).
+3. Assign execute permission to the script: `chmod u+x preview_powermodelsacdc_docs.sh`.
+4. Run the script.
+5. Open your favorite web browser and navigate to `http://localhost:8000`.

docs/make.jl

@@ -1,30 +1,29 @@
 using Documenter, PowerModelsACDC
 
-Documenter.makedocs(
-    modules = PowerModelsACDC,
-    format = Documenter.HTML(),
+makedocs(
+    modules = [PowerModelsACDC],
     sitename = "PowerModelsACDC",
-    authors = "Frederik Geth, Hakan Ergun",
+    warnonly = :missing_docs,
     pages = [
-        "Home" => "index.md",
+        "Home" => "index.md"
         "Manual" => [
-            "Getting Started" => "quickguide.md",
-            "Results" => "result-data.md",
-        ],
+            "Getting Started" => "quickguide.md"
+            "Results" => "result-data.md"
+        ]
         "Library" => [
-            "Network Formulations" => "formulations.md",
-            "Problem Specifications" => "specifications.md",
-            "Problem Types" => "problems.md",
+            "Network Formulations" => "formulations.md"
+            "Problem Specifications" => "specifications.md"
+            "Problem Types" => "problems.md"
             "Modeling Components" => [
-                "Objective" => "objective.md",
-                "Variables" => "variables.md",
-                "Constraints" => "constraints.md",
-            ],
+                "Objective" => "objective.md"
+                "Variables" => "variables.md"
+                "Constraints" => "constraints.md"
+            ]
             "File IO" => "parser.md"
-        ],
+        ]
     ]
 )
 
-Documenter.deploydocs(
+deploydocs(
     repo = "github.com/Electa-Git/PowerModelsACDC.jl.git"
 )

docs/src/index.md

@@ -1,4 +1,4 @@
-# PowerModelACDC.jl Documentation
+# PowerModelsACDC.jl Documentation
 
 ```@meta
 CurrentModule = PowerModelsACDC
@@ -26,16 +26,17 @@ Developed by:
 - Hakan Ergun, Jay Dave, KU Leuven / EnergyVille
 - Frederik Geth, CSIRO
 
-## Installation of PowerModelACDC
+## Installation of PowerModelsACDC
 
-The latest stable release of PowerModelACDC can be installed using the Julia package manager with
+The latest stable release of PowerModelsACDC can be installed using the Julia package manager with
 
 ```julia
 Pkg.add("PowerModelsACDC")
 ```
-!!! Important
+!!! note
     This is a research-grade optimization package.
 
 ## Special Thanks To
-Jef Beerten (KU Leuven/EnergyVille) for his insights in AC/DC power flow modelling.
-Carleton Coffrin (Los Alamos National Laboratory) for his countless design tips.  
+
+- Jef Beerten (KU Leuven/EnergyVille), for his insights in AC/DC power flow modelling.
+- Carleton Coffrin (Los Alamos National Laboratory), for his countless design tips.