Merge pull request #11 from ErikBuer/docs-enhancement

Integrate doctest and enhanced examples

.github/workflows/BuildDocDryRun.yml

@@ -0,0 +1,17 @@
+name: DocumentationDryRun
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1.6'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        run: julia --project=docs/ docs/make.jl
+

.gitignore

@@ -5,3 +5,6 @@
 *.log
 Manifest.toml
 docs/build/
+
+*.vscode/
+*.DS_Store

Project.toml

@@ -11,11 +11,17 @@ Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
-Parameters = "0.10,0.11,0.12"
 DSP = "0.7"
 FFTW = "1.4.5"
 SpecialFunctions = "2.0"
 julia = "1.6"
+
+[extras]
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+
+[targets]
+test = ["Test", "Documenter"]

docs/Project.toml

@@ -1,2 +1,7 @@
 [deps]
+DSP = "717857b8-e6f2-59f4-9121-6e50c889abd2"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+PyPlot = "d330b81b-6aea-500a-939a-2ce795aea3ee"
+SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"

docs/make.jl

@@ -1,20 +1,24 @@
 push!(LOAD_PATH, "../src/")
+
 using Documenter, DigitalComm
 
-makedocs(sitename="DigitalComm.jl", 
-		 format = Documenter.HTML(),
-		 pages    = Any[
-						"Introduction to DigitalComm"   => "index.md",
-						"Function list"          => "base.md",
-						"Examples"                => Any[ 
-														 "Examples/example_AWGN.md",
-														 "Examples/example_BER.md",
-														 "Examples/example_PSD.md",
-														 ],
-						],
-		 );
+DocMeta.setdocmeta!(DigitalComm, :DocTestSetup, :(using DigitalComm); recursive=true)
 
-#makedocs(sitename="My Documentation", format = Documenter.HTML(prettyurls = false))
+makedocs(
+	modules = [DigitalComm],
+	sitename="DigitalComm.jl",
+	format = Documenter.HTML(),
+	pages    = Any[
+		"Introduction to DigitalComm"   => "index.md",
+		"Function list"          		=> "base.md",
+		"Examples"                		=> Any[ 
+											"Examples/example_AWGN.md",
+											"Examples/example_BER.md",
+											"Examples/example_PSD.md",
+										],
+	],
+	doctest  = true,
+);
 
 deploydocs(
     repo = "github.com/JuliaTelecom/DigitalComm.jl",

docs/src/Examples/example_AWGN.md

@@ -1,44 +1,47 @@
-# Transmission of xQAM with additive white Gaussian noise 
+# Transmission of xQAM with additive white Gaussian noise
 
 To simulate a transmission of QPSK // 16QAM // 64QAM // 256QAM other a
 white additive Gaussian noise and display the received constellation,
-the following code can be used 
-
-    # ---------------------------------------------------- 
-    # --- Transmitter
-    # ---------------------------------------------------- 
-    using DigitalComm 
-    using Plots 
-    # --- Parameters 
-    snr		  = 20;
-    mcs		  = 16;
-    nbBits	  = 1024* Int(log2(mcs));
-    # --- Binary sequence generation 
-    bitSeq	  = genBitSequence(nbBits);
-    # --- QPSK mapping
-    qamSeq	  = bitMappingQAM(mcs,bitSeq);
-    # ---------------------------------------------------- 
-    # --- Channel  
-    # ---------------------------------------------------- 
-    #  --- AWGN
-    # Theoretical power is 1 (normalized constellation)
-    qamNoise,  = addNoise(qamSeq,snr,1);
-    # ----------------------------------------------------
-    # --- Rx Stage: SRRC
-    # ----------------------------------------------------
-    # --- Binary demapper
-    bitDec	= bitDemappingQAM(mcs,qamNoise);
-    # --- BER measure
-    ber	  = sum(xor.(bitDec,bitSeq)) /length(bitSeq);
-    # --- Display constellation 
-    plt	  = scatter(real(qamNoise),imag(qamNoise),label="Noisy");
-	scatter!(plt,real(qamSeq),imag(qamSeq),label="Ideal");
-	xlabel!("Real part");
-	ylabel!("Imag part");
-    display(plt);
-
-It plots the received constellation impaired by noise (here a 20dB SNR is used) 
-![Constellation](./../img/constellation.png)
+the following code can be used
 
+## Transmitter
 
+```@example AWG
+using ..DigitalComm # hide
+using Plots 
+# --- Parameters 
+snr       = 20;
+mcs       = 16;
+nbBits    = 1024* Int(log2(mcs));
+# --- Binary sequence generation 
+bitSeq    = genBitSequence(nbBits);
+# --- QPSK mapping
+qamSeq    = bitMappingQAM(mcs,bitSeq); nothing
+```
 
+## Channel
+
+```@example AWG
+#  --- AWGN
+# Theoretical power is 1 (normalized constellation)
+qamNoise,  = addNoise(qamSeq,snr,1); nothing
+```
+
+## Recevicer
+
+```@example AWG
+# --- Binary demapper
+bitDec  = bitDemappingQAM(mcs,qamNoise);
+# --- BER measure
+ber   = sum(xor.(bitDec,bitSeq)) /length(bitSeq);
+# --- Display constellation 
+plt   = scatter(real(qamNoise),imag(qamNoise),label="Noisy");
+scatter(plt,real(qamSeq),imag(qamSeq),label="Ideal");
+xlabel!("Real part");
+ylabel!("Imag part");
+
+savefig("constellation.svg"); nothing # hide
+```
+
+It plots the received constellation impaired by noise (here a 20dB SNR is used)
+![Constellation](constellation.svg)