Run the documentation build as part of the tests and continuous integration
The documentation for `QuantumOptics` (and some of `QuantumOpticsBase`) is in [a separate repository](https://github.com/qojulia/QuantumOptics.jl-documentation/tree/master). 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`](https://github.com/qojulia/QuantumOptics.jl/tree/master/.github/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](https://github.com/qojulia/QuantumOpticsBase.jl/blob/master/.github/workflows/docs.yml) or [the `docs` subtask in the CI for QuantumClifford.jl](https://github.com/QuantumSavory/QuantumClifford.jl/blob/master/.github/workflows/ci.yml#L63). 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`](https://github.com/qojulia/QuantumOpticsBase.jl/blob/master/.github/workflows/breakage.yml#L38), 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](https://github.com/QuantumSavory/QuantumClifford.jl/blob/master/test/test_doctests.jl)
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](https://docs.julialang.org/en/v1/) and [modern workflows](https://modernjuliaworkflows.org/)
- try out VSCode with the [Julia plugin](https://www.julia-vscode.org/) for good IDE support
5 条评论