Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
Krastanov opened this issue Aug 17, 2023 · 8 comments
Closed

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

Krastanov opened this issue Aug 17, 2023 · 8 comments

Comments

@Krastanov
Copy link
Collaborator

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

Noticed by @karolpezet at #372

@Krastanov
Copy link
Collaborator Author

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
Copy link
Member

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

@Krastanov
Copy link
Collaborator Author

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
Copy link
Member

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
Copy link
Collaborator Author

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
Copy link
Member

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
Copy link
Collaborator Author

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.

@Krastanov
Copy link
Collaborator Author

the doc issues have been fixed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants