Documenting OSCAR code
The general philosophy of the OSCAR documentation is to put as much of the information as possible into the docstrings and only use the doc pages for collecting this information and provide some additional general context. Exceptions to this philosophy are the developer and general pages.
Docstrings of exported functions
Exported function should have docstrings, which look like
@doc Markdown.doc""" functionname(x::ArgumentType, b::OtherArgument; c::Keyword = default) -> Int, Int A short description of the function. It is allowed to use $\LaTeX$. """ functionname(x...,b...; c = ...)
If the signature is too long, use linebreaks to fit 80 characters.
Please also do provide an example within the docstring if possible, preferably as a
@doc Markdown.doc""" functionname(x::ArgumentType, b::OtherArgument; c::Keyword = default) -> Int, Int A short description of the function. It is allowed to use $\LaTeX$. # Examples This shows that `functionname` does the right thing for input `input` ```jldoctest julia> input = ... julia> functionname(input) output ``` """ functionname(x...,b...; c = ...)
This allows the user to immediately see how the function can be used, gives them some code that they can copy-paste and manipulate, and, as a bonus, provides a testcase as well.
docs/src contains the OSCAR documentation website. Most of the pages are relatively sparse and consist of
```@docs some_function some_other_function [...] ```
blocks that simply pull in the docstring from the corresponding source file. If you add a new page in
docs/src, you will have to modify
docs/doc.main to include your new page in the appropriate place.
Building the OSCAR documentation with
Once you have created a pull request it is possible to preview the documentation on github using the link https://docs.oscar-system.org/previews/PR<prnumber>/ where you insert the number of your PR for
prnumber. Alternatively you can look at the github actions tab of your PR and click the details link next to the
documenter/deploy action. There are a few conditions for this to work:
- No conflicts with the master branch.
- Documentation action is successful, i.e. no doctest errors.
- The branch for the PR is in the main
You can still build the documentation locally with the commands described below.
build_doc(; doctest=false, strict=false, open_browser=true)
Build the manual of
Oscar.jl locally and open the front page in a browser.
The optional parameter
doctest can take three values:
false: Do not run the doctests (default).
true: Run the doctests and report errors.
:fix: Run the doctests and replace the output in the manual with the output produced by Oscar. Please use this option carefully.
In github actions the Julia version used for building the manual and running the doctests is 1.6. Using a different Julia version will produce errors in some parts of Oscar, so please be careful, especially when setting
The optional parameter
strict is passed on to
Documenter.jl and if set to
true then according to the manual of
Documenter.jl "a doctesting error will always make makedocs throw an error in this mode".
To prevent the opening of the browser at the end, set the optional parameter
When working on the manual the
Revise package can significantly sped up running
build_doc. First, install
Revise in the following way:
using Pkg ; Pkg.add("Revise")
Second, restart Julia and load
Revise before Oscar:
using Revise, Oscar;
The first run of
build_doc will take the usual few minutes, subsequently runs will be significantly faster.
Please also read the section below on repairing the
It is possible to have julia fix the output of all
jldoctests when your changes to the code entail changes to the output. Just run the following command:
build_doc(doctest = :fix)
Please use this command carefully:
- Make sure to only commit the changes to the doctests originating from your changes to the code.
- The doctests also serve as actual tests, so make absolutely sure that the output is still mathematically correct.
If this command fails with an error message indicating lacking permissions to change
AbtractAlgebra.jl related docs, it may help to run the following command:
Updating the bibliography
docs/oscar_references.bib please follow the style of the existing entries. An easy way to do that is to add your new BibTeX entry, then run bibtool by invoking it as follows from the root directory of the Oscar.jl repository:
bibtool docs/oscar_references.bib -o docs/oscar_references.bib
For every pull request on github, the CI checks if running
bibtool leads to changes in the bibliography. If so, this test fails and indicates that the (recently) added bibliography entries are not standardized. For a merge, it is not required that this test is passed. Still, please feel encouraged to fix this failure by running
bibtool locally as explained above.