Add docs

Author: uvegege

.github/workflows/CI.yml

@@ -24,7 +24,6 @@ jobs:
       matrix:
         version:
           - '1.10'
-          - '1.6'
           - 'pre'
         os:
           - ubuntu-latest

.github/workflows/Documenter.yml

@@ -0,0 +1,41 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main # update to match your development branch (master, main, dev, trunk, ...)
+    tags: '*'
+  pull_request:
+
+# Cancel previous runs if a new one is triggered (by push on PR)
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    permissions:
+      contents: write
+      statuses: write
+    runs-on: ubuntu-20.04
+    environment: production
+    steps:
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y xorg-dev mesa-utils xvfb libgl1 freeglut3-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxext-dev xsettingsd x11-xserver-utils
+
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1.10'
+
+      - name: Install Julia dependencies
+        run: |
+          DISPLAY=:0 xvfb-run -s '-screen 0 1024x768x24' julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+
+      - name: Build and Deploy Docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+          GKSwstype: "100"
+        run: |          
+          DISPLAY=:0 xvfb-run -s '-screen 0 1024x768x24' julia --project=docs/ --color=yes docs/make.jl

.gitignore

@@ -1 +1,3 @@
 /Manifest.toml
+/docs/Manifest.toml
+/docs/build

Project.toml

@@ -1,7 +1,7 @@
 name = "SmithChart"
 uuid = "0c39085a-4a17-4c0c-9861-c4c53bcea38a"
 authors = [""]
-version = "0.1.0"
+version = "0.1.1"
 
 [deps]
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
@@ -10,8 +10,10 @@ Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 [compat]
 julia = "1.8.5"
 Makie = "0.20.10"
+
 [extras]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test"]
+test = ["Test", "Documenter"]

README.md

@@ -7,6 +7,8 @@ This project originated as an exploration of the interactive possibilities that
 
 **Note**: Some of the features are experimental. They might not function fully as expected or could be subject to changes in future versions. 
 
+Some examples are shown below. For more information and other examples, visit the documentation.
+
 ## Usage
 
 ```julia
@@ -39,7 +41,6 @@ fig
 
 ![SmithChartExample](Images/smithplot_color.png)
 
-
 ## Integration with Makie
 
 This example showcases the seamless integration of the Smith chart with Makie.jl's interactive functionalities. It demonstrates a typical scenario used to teach impedance matching, where we aim to transform a source impedance of 50+100j $\Omega$ to a load impedance of 50 $\Omega$. To achieve this, we utilize a transmission line and a parallel stub, and control their lengths via sliders. By dynamically adjusting these lengths, users can observe how the source impedance seen by the load evolves on the Smith chart, visually illustrating the impedance matching process.
@@ -91,190 +92,8 @@ fig
 
 ![slidergif](Images/sliders.gif)
 
-## Plot Reflection Coefficientes
-
-You can also draw reflection data with the `reflection = true` keyword. This is useful, for example, when you want to visualize the S-parameters of a simulation or measurement.
-
-```julia
-zi = 3.8 - 1.9im
-function simline(z, l)
-    bl = 2 * pi * l 
-    return (z + im * tan(bl)) / (1 + im * z * tan(bl))
-end
-l = range(0.0, 0.22, 101) 
-z = simline.(zi, l)
-fig = Figure(size = (900,600))
-ax = SmithAxis(fig[1,1])
-smithplot!(ax, z, label = "Impedance")
-# Convert impedance z to reflection
-Γ = @. (z-1)/(z+1)
-# Plot with `reflection = true`
-smithscatter!(ax, Γ[1:5:end], reflection = true, markersize = 11, color = :orange, marker = :cross, label = "Reflection\nreflection = true")
-fig[1,2] = Legend(fig, ax)
-fig
-```
-![ReflectionExample](Images/Reflectionkeyword.png)
-
-
 ## Interactive Data Markers
 
 Interactive data markers can be added to your Smith chart using the `datamarkers(sc::SmithAxis, gp::GridPosition)` function. Double-click on lines or scatter plots to place a marker. To remove a marker, double-click on it. It is possible to move the marker by dragging it with the left click.
 
-![datamarkergif](Images/datamarker_drag.gif)
-
-
-## Stability, Gain and Noise Circles
-
-SmithChart.jl allows visualization of constant gain circles, constant noise circles, and stability regions, essential for amplifier design and stability analysis. These features can be useful for tasks such as designing low-noise amplifiers (LNAs), power amplifiers, and ensuring the stability of circuits over a range of frequencies and impedances.
-
-This example shows how to use the `NFCircle` and `CGCircle`. This functions returns an array of `Point2f` that can be used with Makie functions like `lines!` or `poly!`. 
-
-```julia
-using CairoMakie
-f = Figure(size = (1200, 660))
-sc = SmithAxis(f[1,1], cutgrid = true, title = "Constant NF Circles")
-
-NF_to_F(nf) = 10.0^(nf/10.0)
-Γopt = 0.5 * cis(130 * pi / 180)
-NFmin = 1.6 # dB
-Fmin = NF_to_F(NFmin)
-F2dB = NF_to_F(2.0)
-F2_5dB = NF_to_F(2.5)
-F3dB = NF_to_F(3.0)
-nf2 = NFCircle(F2dB, Fmin, Γopt, 20.0, 50.0, 361)
-nf2_5 = NFCircle(F2_5dB, Fmin, Γopt, 20.0, 50.0, 361)
-nf3 = NFCircle(F3dB, Fmin, Γopt, 20.0, 50.0, 361)
-
-smithscatter!(sc, [Γopt], reflection = true, color = :blue, linewidth = 1.9)
-text!(sc, "Γopt", position = Point2f(real(Γopt), imag(Γopt)),  offset  = (3, 3), color = :blue, font = :bold)
-text!(sc, "$NFmin dB", position = Point2f(real(Γopt), imag(Γopt)),  offset  = (0, -16), color = :blue, font = :bold)
-
-lines!(sc, nf2, color = :green, linewidth = 1.9)
-text!(sc, "2.0 dB", position = nf2[45],  offset  = (2, 0), color = :green, font = :bold)
-
-lines!(sc, nf2_5, color = :purple, linewidth = 1.9)
-text!(sc, "2.5 dB", position = nf2_5[120],  offset  = (-35, 2), color = :purple, font = :bold)
-
-lines!(sc, nf3, color = :orange, linewidth = 1.9)
-text!(sc, "3.0 dB", position = nf3[260],  offset  = (2, 2), color = :orange, font = :bold)
-
-# https://www.allaboutcircuits.com/technical-articles/designing-a-unilateral-rf-amplifier-for-a-specified-gain/
-sc = SmithAxis(f[1,2], cutgrid = true, title = "Constant Gs Circles")
-
-S11 = 0.533 * cis(176.6 / 180 * π)
-S22 = 0.604 * cis(-58.0 / 180 * π)
-Go = abs2(S11)
-Gs_max = 1 / (1 - abs2(S11))
-gain(dB) = 10.0^(dB/10.0)
-
-g1 = gain(0.0) / Gs_max
-g2 = gain(0.5) / Gs_max
-g3 = gain(1.0) / Gs_max
-g4 = gain(1.4) / Gs_max
-
-c1 = CGCircle(g1, S11, 361)
-c2 = CGCircle(g2, S11, 361)
-c3 = CGCircle(g3, S11, 361)
-c4 = CGCircle(g4, S11, 361)
-
-smithscatter!(sc, [conj(S11)], reflection = true, color = :blue, linewidth = 1.9)
-text!(sc, "S11*", position = Point2f(real(S11), -imag(S11)),  
-    offset  = (-5, 7), color = :blue, font = :bold, fontsize = 9)
-
-poly!(sc, c1, color = (:green, 0.1), strokecolor = :green, strokewidth = 1.9)
-text!(sc, "0.0 dB", position = c1[125],  offset  = (17, 0), color = :green, font = :bold)
-
-lines!(sc, c2, color = :red, linewidth = 1.9)
-text!(sc, "0.5 dB", position = c2[110],  offset  = (-27, 3), color = :red, font = :bold)
-
-lines!(sc, c3, color = :magenta, linewidth = 1.9)
-text!(sc, "1.0 dB", position = c3[260],  offset  = (2, 0), color = :magenta, font = :bold)
-
-lines!(sc, c4, color = :purple, linewidth = 1.9)
-text!(sc, "1.4 dB", position = c3[45],  offset  = (2, 2), color = :purple, font = :bold)
-```
-
-![Ccircles](Images/ConstantCircles.svg)
-
-When calculating the stability regions, you can select whether you want to display the stable or unstable region. To do this, modify the keyword `stable` in the `StabilityCircle` function.
-
-```julia
-using CairoMakie
-f = Figure(size = (800, 500))
-Label(f[0, 1:2] , "Stable Regions", fontsize = 24, font = :bold)
-S11, S12, S21, S22 =  [0.438868-0.778865im 1.4+0.2im; 0.1+0.43im  0.692125-0.361834im]
-A =  StabilityCircle(S11, S12, S21, S22, :source, 361; stable = false)
-B =  StabilityCircle(S11, S12, S21, S22, :source, 361; stable = true)
-
-ax = SmithAxis(f[1,1], subtitle = "StabilityCircle(... ; stable = false)")
-region = poly!(ax, A, strokecolor = :black, strokewidth = 1.2, color = Pattern('x', linecolor = :red, width = 1.3, background_color = (:red, 0.1)))
-translate!(region, (0, 0, -2)) 
-text!(ax, "Unstable Input", position = Point2f(-0.1, -0.5), font = :bold, color = :red, fontsize = 15)
-B =  StabilityCircle(S11, S12, S21, S22, :source, 361; stable = true);
-ax = SmithAxis(f[1,2], subtitle = "StabilityCircle(... ; stable = true)")
-region = poly!(ax, B, strokecolor = :black, strokewidth = 1.2, color = Pattern('\\', linecolor = :blue, width = 1.3, background_color = (:blue, 0.1)))
-translate!(region, (0, 0, -2)) 
-text!(ax, "Stable Input", position = Point2f(0.1, 0.15), font = :bold, color = :blue, fontsize = 15)
-```
-![stabilityregions1](Images/bothregions.svg)
-
-It is possible to obtain the input or output stability regions with `StabilityCircle(S11, S12, S21, S22, :source, npoints)` or `StabilityCircle(S11, S12, S21, S22, :load, npoints)`.
-
-```julia
-f = Figure()
-S11, S12, S21, S22 = [ 0.0967927-0.604297im  0.0255292+0.0394621im ; -8.4396+11.0786im    0.552226-0.425271im]
-A =  StabilityCircle(S11, S12, S21, S22, :source, 361; stable = true);
-B =  StabilityCircle(S11, S12, S21, S22, :load, 361; stable = true);
-ax = SmithAxis(f[1,1], title = "Input and Output stability regions")
-color1 = Pattern('/', linecolor = :blue, width = 1.3, background_color  = :transparent)
-color2 = Pattern('\\', linecolor = :green, width = 1.3, background_color  = :transparent)
-region = poly!(ax, A, strokecolor = :black, strokewidth = 1.2, color = color1)
-translate!(region, (0, 0, -2)) 
-region = poly!(ax, B, strokecolor = :black, strokewidth = 1.2, color = color2)
-translate!(region, (0, 0, -2)) 
-text!(ax, "Stable Input", position = Point2f(-0.85, 0.2), font = :bold, color = :blue, rotation = 25*pi/180, fontsize = 12)
-text!(ax, "Stable Output", position = Point2f(0.3, 0.5), font = :bold, color = :green, rotation = -18*pi/180, fontsize = 12)
-```
-
-![stabilityregions2](Images/StableRegionsLines.svg)
-
-
-## Dynamic Annotation Update
-
-You can activate a experimental dynamic curve annotation with the keyword `textupdate = true`
-
-```julia
-fig = Figure(size = (800,600))
-ax = SmithAxis(fig[1, 1]; subgrid = true, cutgrid = true, zoomupdate = true, textupdate = true, threshold = (150, 150))
-```
-
-![ZoomGif](Images/SmithChart_zoom.gif)
-
-
-## Other Keywords
-
-How some keywords modify visual aspects of the Smith Chart.
-
-### Chart type and grid colors
-
-It is possible to change the type of smith chart or modify the color of the grid or subgrid.
-
-![keywordexample](Images/typeandcolor.png)
-
-### Interior tick options
-
-There are multiple keywords to modify the position of the ticks. Some of them are:
-
-![keywordexample](Images/tickkeywords.png)
-
-### Threshold keyword
-
-`threshold` keyword controls the cut of the lines in the intersection with other arcs.
-
-![keywordexample](Images/threshold.png)
-
-### Subgrid split
-
-The `splitgrid` keyword controls the number of cuts for each zoomlevel.
-
-![keywordexample](Images/splitminor.png)
+![datamarkergif](Images/datamarker_drag.gif)

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+Bonito = "824d6782-a2ef-11e9-3a09-e5662e0c26f8"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
+SmithChart = "0c39085a-4a17-4c0c-9861-c4c53bcea38a"

docs/make.jl

@@ -0,0 +1,25 @@
+using Documenter, SmithChart
+
+DocMeta.setdocmeta!(SmithChart, :DocTestSetup, :(using SmithChart); recursive=true)
+
+makedocs(modules = [SmithChart], clean = true,  format = Documenter.HTML(; size_threshold=100_000_000), sitename = "SmithChart.jl", 
+    pages = Any[
+    "index.md",
+    "SmithAxisBlock.md",
+    "api_reference.md",
+    "Examples" => Any[
+        "Examples/ChartTypes.md",
+        "Examples/TickPositions.md",
+        "Examples/MakieIntegration.md",
+        "Examples/Reflection.md", 
+        "Examples/InteractiveDataMarkers.md",
+        "Examples/ConstantCircles.md", 
+        "Examples/VisualDetails.md",
+        "Examples/DynamicUpdate.md"]
+        ], doctest = true, checkdocs=:none)
+     
+deploydocs(
+    repo = "github.com/uvegege/SmithChart.jl.git",
+    push_preview = true,
+)
+

docs/src/Examples/ChartTypes.md

@@ -0,0 +1,18 @@
+# Chart type and grid colors
+
+Change type and control color of the grid or subgrid. The keywords `zgridcolor` and `ygridcolor` allow controlling both axes with a single keyword. Each of them takes precedence over their respective individual grid color settings (`rgridcolor` and `xgridcolor` for the Z-axis, and `bgridcolor` and `ggridcolor` for the Y-axis).
+
+```@example
+using SmithChart
+using CairoMakie
+CairoMakie.activate!() #hide
+f = Figure(size = (1200, 800))
+sc1 = SmithAxis(f[1,1], type = :Z, subtitle = "type :Z (default)")
+sc2 = SmithAxis(f[1,2], type = :Y, subtitle = "type :Y")
+sc3 = SmithAxis(f[1,3], type = :ZY, subtitle = "type :ZY", gtickvisible = false, btickvisible = false)
+sc4 = SmithAxis(f[2,1], type = :Z, subtitle = "rgridcolor = :red, xgridcolor = :green", rgridcolor = :red, xgridcolor = :green)
+sc5 = SmithAxis(f[2,2], type = :Y, subtitle = "ygridcolor = :blue", ygridcolor = :blue)
+sc6 = SmithAxis(f[2,3], type = :ZY, subtitle = "zgridcolor = :orange, ygridcolor = :green", zgridcolor = :orange, ygridcolor = :green, gtickvisible = false, btickvisible = false)
+f
+```
+