Run the documentation build as part of the tests and continuous integration

[Krastanov]

The documentation for QuantumOptics (and some of QuantumOpticsBase) is in a separate repository. This was done for historic reasons, and while it is not necessary anymore, it is still a relatively convenient setup.

One drawback though, is that the documentation build and related tests are not executed when a pull request is submitted. Like with many other open source projects, we use "continuous integration" (CI), where each RP and every commit in the PR is tested. We mostly use github actions as defined in the workflows folder.

This bounty is about ensuring that "documentation building" is executed as part of the CI.

The value of doing so is not only in keeping the docs up to date, but also in detecting issues like misspelled exports, typos in docstrings, etc.

To see how to structure a CI configuration file for running docs, see docs.yml in QuantumOpticsBase.jl or the docs subtask in the CI for QuantumClifford.jl. You do not need to worry about the deployment of the docs, just running their build step.

However, for this particular case you will need to clone the separate repository that contains the documentation. A convenient reference to see how to structure such a step is the run section of the breakage.yml CI action in QuantumOpticsBase.jl, which runs tests from other repositories when someone makes a change to the QuantumOpticsBase.jl repository.

A good first step would be just to make sure that you can build the docs locally, as that would be the main part of the script you need to write in the new CI action file. To do so you would need something similar to:

julia --project=FOLDER_WITH_DOCS -e '
                     using Pkg
                     Pkg.develop(PackageSpec(path=FOLDER_WITH_QUANTUMOPTICS_REPO))
                     Pkg.instantiate()';
julia --project=FOLDER_WITH_DOCS -i FOLDER_WITH_DOCS/make.jl

Additionally, make sure the doctests are being executed, e.g. as seen in QuantumClifford

To complete this bounty:

• create the new action files for QuantumOptics.jl and QuantumOpticsBase.jl
• make sure they run successfully
• correct any failures that might be detected
• add a specific doctest runner for each of the two repos as well

If you are new to julia, make sure to:

• install julia using juliaup for version management
• look through the julia manual and modern workflows
• try out VSCode with the Julia plugin for good IDE support

[ErikQQY]

I am curious why not keep the documents for QuantumOptics.jl inside the docs/ folder of QuantumOptics.jl? That would be more convenient and can be directly deployed in gh-pages branch?

[Krastanov]

That would work. Years ago before Documenter.jl was mature, this library used the python sphinx package. Back then that seemed necessary. We can move this back to a more standard deployment.

Either option would count as a solution of the bounty.

@david-pl , we might need some extra configuration access to the github org to completely fix this. Flagging you so you are aware of this process.

[Krastanov]

Just make sure that the examples also work correctly (they are in yet another repo). To be fair, while either solution counts, it would probably be much simpler to stick to the current setup.

[Krastanov]

my guess (only a guess) is that the script is started from the wrong directory and can not find the correct files (because it uses relative paths)