search

qojulia / QuantumOptics.jl

Library for the numerical simulation of closed as well as open quantum systems.
http://qojulia.org
Other
518 stars 101 forks source link

docs do not seem to show methods implemented in QuantumOpticsBase #373

Open Krastanov opened 10 months ago

Krastanov commented 10 months ago

Compare https://docs.qojulia.org/search/?q=squeeze and https://qojulia.github.io/QuantumOpticsBase.jl/latest/search/?q=squeeze

Noticed by @karolpezet at https://github.com/qojulia/QuantumOptics.jl/pull/372

Krastanov commented 10 months ago

We should probably create a "Full API" page in addition to the curated API page (https://github.com/qojulia/QuantumOptics.jl-documentation/blob/master/src/api.md) that just list everything

ChristophHotter commented 10 months ago

@Krastanov I think we should just complete the existing API (I briefly talked to @david-pl). I can do this at some point.

Krastanov commented 10 months ago

I agree, it would be great to extend the curated list. The suggestion for a hidden "Full API" page is more so that future omissions like this (which will inevitably happen) do not cause even the search function to fail.

Some combination of multidocumenter and strict warnings during build can also help.

ChristophHotter commented 10 months ago

I included now all the missing APIs in the docu. When you build the documentation you get a warning for all the missing APIs.

Krastanov commented 10 months ago

What I am suggesting is turning that warning into an error, so it gets detected during pull requests. Like here: https://github.com/QuantumSavory/QuantumClifford.jl/blob/master/docs/make.jl#L24

One just needs to be careful: there is a particular warning type that shows up when an unexported method with a docstring is NOT in the public documentation. But unexported methods are usually private and can break at any time, so it is correct to not have them in the documentation. The except tool can be used to disregard those.

ChristophHotter commented 10 months ago

I guess this would be beneficial. However, when I build the docu I always obtain the following strange warning which would turn into an error: Warning: no doc found for reference '[SparseOperator](@ref)' in src/api.md. └ @ Documenter.CrossReferences ~/.julia/packages/Documenter/bYYzK/src/Utilities/Utilities.jl:34 I do not know where this comes from, do you have any idea?

Krastanov commented 10 months ago

Not certain, but presumably the docstring for SparseOperator is not visualized anywhere in the docs. Adding an autodoc for it (or adding a hidden page with autodoc for all public symbols) would probably solve this.