QuantumSavory / QuantumSavory.jl

A full stack simulator of quantum hardware, from the low-level analog physics to high-level network dynamics. Includes discrete event simulator, symbolic representation for quantum object, and works with many backend simulators.
https://quantumsavory.github.io/QuantumSavory.jl/
MIT License
37 stars 15 forks source link

documentation polish for StateZoo API #64

Closed Krastanov closed 11 months ago

Krastanov commented 11 months ago

The docstrings for some StateZoo objects get rendered redundantly.

See e.g. https://quantumsavory.github.io/QuantumSavory.jl/dev/API_StatesZoo/#QuantumSavory.StatesZoo.DualRailMidSwapBellW

Due to https://github.com/QuantumSavory/QuantumSavory.jl/blob/e33370e9225a864b56be42b1ffb56f4e0160bae3/src/StatesZoo/zalm_pair/zalm_pair.jl#L628

Julia's documenter is smart enough to use per-parameter docstrings. Move the current docstrings in per-parameter docstrings.

image

If that breaks the @withmetadata macro, file an issue about it and leave the PR open for later -- no need to invest too much time on it.

ba2tro commented 11 months ago

Yep, it doesn't precompile with the @withmetadata macro there, works as expected when its removed

julia> using QuantumSavory
[ Info: Precompiling QuantumSavory [2de2e421-972c-4cb5-a0c3-999c85908079]
┌ Warning: Fock space cutoff is not specified so we default to 2
└ @ QuantumOpticsExt C:\Users\Abhishek Bhatt\.julia\packages\QuantumSymbolics\QFyHe\ext\QuantumOpticsExt\QuantumOpticsExt.jl:74
ERROR: LoadError: type String has no field head
Stacktrace:
  [1] getproperty
    @ .\Base.jl:37 [inlined]
  [2] (::QuantumSymbolics.var"#1#4")(x::String)
    @ QuantumSymbolics C:\Users\Abhishek Bhatt\.julia\packages\QuantumSymbolics\QFyHe\src\QSymbolicsBase\QSymbolicsBase.jl:92
  [3] _all(f::QuantumSymbolics.var"#1#4", itr::Vector{Any}, #unused#::Colon)
    @ Base .\reduce.jl:1283
  [4] all(f::Function, a::Vector{Any}; dims::Function)
    @ Base .\reducedim.jl:1007
  [5] all(f::Function, a::Vector{Any})
    @ Base .\reducedim.jl:1007
  [6] withmetadata(strct::Expr)
    @ QuantumSymbolics C:\Users\Abhishek Bhatt\.julia\packages\QuantumSymbolics\QFyHe\src\QSymbolicsBase\QSymbolicsBase.jl:92
  [7] var"@withmetadata"(__source__::LineNumberNode, __module__::Module, strct::Any)
    @ QuantumSymbolics C:\Users\Abhishek Bhatt\.julia\packages\QuantumSymbolics\QFyHe\src\QSymbolicsBase\QSymbolicsBase.jl:78     
  [8] #macroexpand#63
    @ .\expr.jl:119 [inlined]
  [9] macroexpand
    @ .\expr.jl:117 [inlined]
 [10] docm(source::LineNumberNode, mod::Module, meta::Any, ex::Any, define::Bool)
    @ Base.Docs .\docs\Docs.jl:539
 [11] docm(source::LineNumberNode, mod::Module, meta::Any, ex::Any)
    @ Base.Docs .\docs\Docs.jl:539
 [12] (::DocStringExtensions.var"#35#36"{typeof(DocStringExtensions.template_hook)})(::LineNumberNode, ::Vararg{Any})
    @ DocStringExtensions C:\Users\Abhishek Bhatt\.julia\packages\DocStringExtensions\JVu77\src\templates.jl:11
 [13] var"@doc"(__source__::LineNumberNode, __module__::Module, x::Vararg{Any})
    @ Core .\boot.jl:539
 [14] include(mod::Module, _path::String)
    @ Base .\Base.jl:457
 [15] include(x::String)
    @ QuantumSavory.StatesZoo C:\Users\Abhishek Bhatt\.julia\dev\QuantumSavory\src\StatesZoo\StatesZoo.jl:1
 [16] top-level scope
    @ C:\Users\Abhishek Bhatt\.julia\dev\QuantumSavory\src\StatesZoo\StatesZoo.jl:56
 [17] include(mod::Module, _path::String)
    @ Base .\Base.jl:457
 [18] include(x::String)
    @ QuantumSavory C:\Users\Abhishek Bhatt\.julia\dev\QuantumSavory\src\QuantumSavory.jl:1
 [19] top-level scope
    @ C:\Users\Abhishek Bhatt\.julia\dev\QuantumSavory\src\QuantumSavory.jl:353
 [20] include
    @ .\Base.jl:457 [inlined]
 [21] include_package_for_output(pkg::Base.PkgId, input::String, depot_path::Vector{String}, dl_load_path::Vector{String}, load_path::Vector{String}, concrete_deps::Vector{Pair{Base.PkgId, UInt128}}, source::Nothing)
    @ Base .\loading.jl:2049
 [22] top-level scope
    @ stdin:3

The problem is that the struct_args here should reject the docstrings

ba2tro commented 11 months ago

Issue: https://github.com/QuantumSavory/QuantumSymbolics.jl/issues/23