GitHub

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 raw"""
    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 jldoctest, i.e.

@doc raw"""
    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.

The folder docs

The folder 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 Oscar.build_doc

Previewing the documentation

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 oscar-system/Oscar.jl repository.

You can still build the documentation locally with the commands described below.

build_doc — Function
build_doc(; doctest=false, warnonly=true, open_browser=true, start_server=false)

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 is 1.10 and doctests are run with >= 1.7. Using a different Julia version may produce errors in some parts of Oscar, so please be careful, especially when setting doctest=:fix.

The optional parameter warnonly is passed on to makedocs of Documenter.jl and if set to false then according to the manual of Documenter.jl "a doctesting error will always make makedocs throw an error in this mode". Alternatively, one can pass a list of symbols to warnonly to suppress errors for the given error types.

To prevent the opening of the browser at the end, set the optional parameter open_browser to false.

Alternatively, one can use the optional parameter start_server to start a web server in the build directory which is accessible via 127.0.0.1:8000. If both start_server and open_browser are true, the browser will show this page. The server keeps running in the background until the julia session is terminated, so the proposed usage for this option is to run build_doc(start_server = true) for the first build and build_doc(open_browser = false) for following builds and only refresh the browser tab.

When working on the manual the Revise package can significantly speed 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, subsequent runs will be significantly faster.

source

Please also read the section below on repairing the jldoctests using build_doc.

Browser reports denied access

Depending on your system, it might happen that the browser opens after a successful build, but only informs you that the access to the file was denied. This happens, for example, on Ubuntu which comes with a sandboxed Firefox. In this case, using build_doc with start_server = true should circumvent this problem.

Automatically repairing jldoctests

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)

If you just want to fix some of the jldoctests, and do not want to build the documentation, you can also use Oscar.doctest_fix:

doctest_fix — Function
doctest_fix(f::Function; set_meta::Bool = false)

Fixes all doctests for the given function f.

Example

The following call fixes all doctests for the function symmetric_group:

julia> Oscar.doctest_fix(symmetric_group)
source
doctest_fix(path::String; set_meta::Bool = false)

Fixes all doctests for all files in Oscar where path occurs in the full pathname.

Example

The following call fixes all doctests in files that live in a directory called Rings (or a subdirectory thereof), so e.g. everything in src/Rings/:

julia> Oscar.doctest_fix("/Rings/")
source
Danger

Please use these commands 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.
Tip

If these commands fail with an error message indicating lacking permissions to change AbstractAlgebra.jl related docs, it may help to run the following command:

]dev AbstractAlgebra

Updating the bibliography

When editing 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.

Please follow the additional guidelines below, that are not checked by bibtool:

  • Do not escape special characters like umlauts or accented characters. Instead, use the unicode character directly.
  • You do not need to use braces to preserve capitalization as DocumenterCitations.jl keeps entries as is (in contrast to bibtex). In some cases, braces can even be harmful, i.e., show up in the output.
  • If a DOI is available for your reference, please add it as a doi field to the BibTeX entry. In this case, please refrain from adding an additional url field.
  • If your reference has no DOI or the paper is not open-access, but is available as an arXiv preprint, you can add the arXiv link as a eprint field (even additionally to a doi field). For other preprint servers (e.g. HAL), please refer to the DocumenterCitations.jl docs.
  • Documents available only as an arXiv preprint should be added as @Misc entries with the arXiv-ID in the eprint field, e.g., archiveprefix = {arXiv} and eprint = {2008.12651}.