About
This page contains some general information about this repository.
Credits
These persons have contributed to JuliaReachDevDocs (in alphabetic order):
Click here to go to the documentation for the latest stable release.'; + div.appendChild(closer); + document.body.appendChild(div); +} + +if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", maybeAddWarning); +} else { + maybeAddWarning(); +} diff --git a/previews/PR56/guidelines/index.html b/previews/PR56/guidelines/index.html new file mode 100644 index 0000000..86fec29 --- /dev/null +++ b/previews/PR56/guidelines/index.html @@ -0,0 +1,155 @@ + +
Coding guidelines
This section is a reference for commonly used coding guidelines adopted in JuliaReach projects. There are several style guides in the Julia ecosystem; see Other style guides for some of them.
Source-code guidelines
In general the guidelines follow the rules in the .JuliaFormatter.toml file.
Use 4 space characters for indentation.
In error messages, make the first word lowercase and do not add a period in the end.
Use empty space in assignments:
n=length(q)(no)n = length(q)(yes)
The previous convention has an exception: using
=in keyword arguments:convex_hull(p, algorithm = "monotone_chain")(no)convex_hull(p, algorithm="monotone_chain")(yes)
Use empty space after commas:
evaluate(p,D)(no)evaluate(p, D)(yes)
Try to stay within 100 characters both for code and documentation. For type and function signatures this usually requires line breaks if there are many arguments or they have long names. In this case we write each argument in a new line if it looks better. If the offending line is a string, you can divide it into smaller chunks with
*, as in:
@assert dim(P) == size(M, 2) "a linear map of size $(size(M)) cannot be " *
+ "applied to a set of dimension $(dim(P))"The 100 characters rule should not be enforced in all cases, but is rather a soft guideline.
Use the full
function f() ... endinstead off() = .... However, the short form is preferable in constructors and aliases such as×(X::LazySet, Y::LazySet) = CartesianProduct(X, Y).Use the following conventions for type parameters:
Nfor numeric typesVNfor vectors of numeric typeNMNfor matrices of numeric typeNSfor set types
To indicate helper functions that are not part of the API, use a leading underscore for the function name, as in
_myfun.Read Julia's Style Guide.
Documentation guidelines
Generating the documentation
To generate the HTML documentation we rely on the docs/make.jl script that is interpreted using Julia's documentation generator package Documenter.jl. You can build the documentation locally and verify the changes with the following command:
$ julia --color=yes docs/make.jlThis will deploy the docs in docs/build with index.html being the start page.
Observe that the docs/build folder is and should not be included in the master branch: in fact, the build system automatically pushes this folder to the gh-pages branch after each commit. This means that each time that a commit is merged into the master branch in Github, the updated documentation will be available as soon as the continuous integration finishes (this usually takes a couple of minutes).
Mathematical notation
Mathematical formulas are written in LaTeX inside double backticks. If possible you should use Unicode; otherwise remember that the backslash character should be written twice.
``\delta[TAB]A``Notice that the string is inside double back-ticks, and that we use the TAB key to transform into Unicode. In those cases where there is no Unicode character, you can use two backslash characters.
``\\mathcal{X}_0``Finally, Documenter can also parse usual LaTeX dollar sign notation for the Markdown files. In that case, only one backslash is needed. For more examples consult Documenter.jl or check the various examples in our project's source code.
Writing docstrings
In this section we give the guidelines for writing docstrings of functions and types. We give two concrete examples. You can find more examples by searching in the source files.
Documenting functions
The docstring of a function should consist of following parts, in the given order:
| Part | Category | Description |
|---|---|---|
| Signature | Mandatory | List the function's name and arguments (include the argument types and the return type, i.e., just copy the signature from the source code; mark optional arguments in brackets) |
| Brief description | Mandatory | One-line purpose of the function |
| Input | Mandatory | All input arguments, optional or not, and valid keyword arguments |
| Output | Mandatory | The return value(s) of the function together with a description; "Nothing." if no value is returned. |
| Notes | Optional | Additional details about the function |
| Algorithm | Optional but recommended | Details on the implementation and the relation to other functions |
| Examples | Optional but recommended | Give concrete, self-contained applications of this function |
Below we provide a concrete example:
"""
+ monotone_chain!(points::Vector{VN}; sort::Bool=true
+ )::Vector{VN} where {VN<:AbstractVector{N}} where {N<:Real}
+
+Compute the convex hull of points in the plane using Andrew's monotone chain
+method.
+
+### Input
+
+- `points` -- list of 2D vectors; is sorted in-place inside this function
+- `sort` -- (optional, default: `true`) flag for sorting the vertices
+ lexicographically; sortedness is required for correctness
+
+### Output
+
+List of vectors containing the 2D coordinates of the corner points of the
+convex hull.
+
+### Notes
+
+For large sets of points, it is convenient to use static vectors to get
+maximum performance. For information on how to convert usual vectors
+into static vectors, see the type `SVector` provided by the
+[StaticArrays](http://juliaarrays.github.io/StaticArrays.jl/stable/)
+package.
+
+### Algorithm
+
+This function implements Andrew's monotone chain convex hull algorithm to
+construct the convex hull of a set of ``n`` points in the plane in
+``O(n \\log n)`` time.
+For further details see
+[Monotone chain](https://en.wikibooks.org/wiki/Algorithm_Implementation/Geometry/Convex_hull/Monotone_chain)
+"""
+function monotone_chain!(points::Vector{VN}; sort::Bool=true
+ )::Vector{VN} where {VN<:AbstractVector{N}} where {N<:Real}
+ ...
+endThe following example has an optional argument, and it is surrounded with square brackets in the docstring by convention.
"""
+ radius(H::Hyperrectangle, [p]::Real=Inf)::Real
+
+Return the radius of a hyperrectangle.
+
+### Input
+
+- `H` -- hyperrectangle
+- `p` -- (optional, default: `Inf`) norm
+
+### Output
+
+A real number representing the radius.
+
+### Notes
+
+The radius is defined as the radius of the enclosing ball of the given
+``p``-norm of minimal volume with the same center.
+"""
+function radius(H::Hyperrectangle, p::Real=Inf)::Real
+ ...
+endDocumenting types
The docstring of a type should consist of the following parts:
| Part | Category | Description |
|---|---|---|
| Signature | Mandatory | Describe the interface of this type (just copy the signature from the source code) |
| Brief description | Mandatory | One-line purpose of the type |
| Fields | Mandatory | Describe each field |
| Notes | Optional | Additional details about the type |
| Examples | Optional but recommended | Construction example (recommended if it has different constructors) |
Below we provide a concrete example:
+"""
+ DiscreteSystem <: AbstractSystem
+
+Type that represents a system of discrete-time affine ODEs with nondeterministic
+inputs,
+
+``x_{k+1} = A x_{k} + u_{k}``
+
+where:
+
+- ``A`` is a square matrix
+- ``x(0) ∈ \\mathcal{X}_0`` and ``\\mathcal{X}_0`` is a convex set
+- ``u_{k} ∈ \\mathcal{U}_{k}``, where ``\\{\\mathcal{U}_{k}\\}_k`` is a
+ set-valued sequence defined over ``[0, δ], ..., [(N-1)δ, N δ]`` for some
+ ``δ>0``
+
+### Fields
+
+- `A` -- square matrix, possibly of type `SparseMatrixExp`
+- `X0` -- set of initial states
+- `U` -- nondeterministic inputs
+- `δ` -- discretization step
+
+### Examples
+
+- `DiscreteSystem(A::Union{AbstractMatrix{Float64}, SparseMatrixExp{Float64}},
+ X0::LazySet,
+ δ::Float64,
+ U::NonDeterministicInput)` -- default constructor
+- `DiscreteSystem(A::Union{AbstractMatrix{Float64}, SparseMatrixExp{Float64}},
+ X0::LazySet,
+ δ::Float64)` -- constructor with no inputs
+- `DiscreteSystem(A::Union{AbstractMatrix{Float64}, SparseMatrixExp{Float64}},
+ X0::LazySet,
+ δ::Float64,
+ U::LazySet)` -- constructor that creates a
+ `ConstantNonDeterministicInput`
+- `DiscreteSystem(A::Union{AbstractMatrix{Float64}, SparseMatrixExp{Float64}},
+ X0::LazySet,
+ δ::Float64,
+ U::Vector{<:LazySet})` -- constructor that creates a
+ `TimeVaryingNonDeterministicInput`
+"""
+struct DiscreteSystem <: AbstractSystem
+ ...
+endThe following is an example of an abstract type, parametric in N, which defines an interface and includes a doctest.
"""
+ AbstractHPolygon{N<:Real} <: AbstractPolygon{N}
+
+Abstract type for polygons in H-representation (i.e., constraints).
+
+### Notes
+
+Every concrete `AbstractHPolygon` must have the following fields:
+- `constraints_list::Vector{LinearConstraint{N}}` -- the constraints
+
+```jldoctest
+julia> subtypes(AbstractHPolygon)
+2-element Array{Union{DataType, UnionAll},1}:
+ LazySets.HPolygon
+ LazySets.HPolygonOpt
+```
+"""
+abstract type AbstractHPolygon{N<:Real} <: AbstractPolygon{N} endWriting doctests
Using Documenter.jl, docstring examples can be incorporated to the doctesting framework using the jldoctest environment, see the Doctests section of the documentation.
Here are some additional tips:
- To have the required modules available in the current file, write the following in triple backticks (e.g., see
docs/src/lib/representations.mdor the documentation):
@meta
+DocTestSetup = quote
+ using LazySets
+endTo preserve definitions between blocks of code you can use labels. For example, use the environment
jldoctest ball2_label.If you use several lines in REPL mode (
julia> ...), you will have to include empty lines between the commands. Otherwise the variables from the previous commands are not available below.The doctests currently take a long time (~1min) because they generate some plots using
Plots.jl. There is a linedoctest = trueinmake.jlwhich you can set tofalseto allow building the documentation but skipping the doctests.
Extending the online documentation
To add a function or a type in the online documentation, put the function's signature or type in a @docs block on the appropriate markdown (.md) file of the /docs/src folder.
For example, let the function
function dim(P::AbstractPolygon)::Int
+ ...
+endIt is added in the documentation of the AbstractPolygon interface, /docs/src/lib/interfaces.md, in the following way:
@docs
+...
+dim(P::AbstractPolygon)Note that output type annotations is not needed. Also the variable's name is not needed and one could equally have written dim(::AbstractPolygon).
In some cases, the function to be added contains an optional input. In those cases only the required arguments are needed. For instance, let:
linear_map(M::AbstractMatrix, P::AbstractPolygon{N};
+ output_type::Type{<:LazySet}=typeof(P)) where {N}This function can be documented in a @docs block as:
linear_map(::AbstractMatrix, P::AbstractPolygon{N}) where NIn cases when there is no function overload, it is sufficient to write the function's name. For example, the function with signature
function convex_hull!(points::Vector{VN};
+ algorithm::String="monotone_chain"
+ )::Vector{VN} where {N<:Real, VN<:AbstractVector{N}}
+...
+endIs documented in /docs/src/lib/operations.md as:
@docs
+...
+convex_hull!Adding plot recipe docstrings
A plot recipe can be added to the docs using the extension RecipesBase.apply_recipe. Moreover, it is important that you use pass the Dict{Symbol,Any}-type argument that corresponds to the plotting options; this argument is added automatically by the @recipe macro. Consider the example below:
"""
+ plot_emptyset(∅::EmptySet, [ε]; ...)
+
+Plot an empty set.
+
+### Input
+
+- `∅` -- empty set
+- `ε` -- (optional, default: `0`) ignored, used for dispatch
+
+### Output
+
+An empty figure.
+"""
+@recipe function plot_emptyset(∅::EmptySet{N}, ε::N=zero(N); label="", grid=true,
+ legend=false) where {N<:Real}
+ return []
+endThis example has an optional argument with default value. Inside a @docs block we can add the docstring as follows:
RecipesBase.apply_recipe(::Dict{Symbol,Any}, ::EmptySet{N}, ::N=zero(N)) where {N<:Real}Resizing an image in the documentation
It is possible with Documenter to add content using raw HTML with the macro @raw. That lets, for example, to include an image and fix the size: between a @raw html block, write
<img src="path/to/image.png" width="25%"/>Other style guides
Below we list other Julia code style guides that we have found interesting.
- Yet Another Style Guide For Julia
- JuMP.jl style guide
- Julia style guide
- ColPrac – Describes some best practices for collaborating on repositories. Following these practices makes it easier for contributors (new and old) to understand what is expected of them.
Settings
This document was generated with Documenter.jl version 1.3.0 on Monday 8 April 2024. Using Julia version 1.10.2.
JuliaReachDevDocs
JuliaReachDevDocs hosts resources for the JuliaReach github organization developers.
Contents
Settings
This document was generated with Documenter.jl version 1.3.0 on Monday 8 April 2024. Using Julia version 1.10.2.
Adding a new package
In this section we describe the usual procedure to add a new package.
Creating the GitHub repository
To create an empty repository, go to your user name and click on New. If you have write access to the JuliaReach org, click on New on the top-right or go to the link Create a new repository.
Creating the Julia package
Using JuliaReachTemplatePkg
The GitHub repository JuliaReachTemplatePkg contains a template package for JuliaReach projects.
Using PkgTemplates
Alternatively, an easy way to create an empty package is to use PkgTemplates. An example is given below:
julia> using PkgTemplates
+
+julia> t = Template(; user="JuliaReach", license="MIT",
+ authors=["Marcelo Forets", "Benoît Legat", "Christian Schilling"],
+ plugins=[TravisCI(), Codecov(), AppVeyor(), GitHubPages()])
+
+julia> generate("MathematicalSets", t)Some settings are used in JuliaReach's projects:
- update the README
- add the style for docs in
docs/assets/juliareach.css
Deploying the documentation
Follow the guidelines described in Documenter.jl's manual: Hosting documentation. In particular, copy the Documenter key from here.
After the first build, set up (i.e., protect, see below) the gh-pages branch and add links to the documentation in the README.md.
Adding requirements
These are links we have found useful:
julia> using Pkg
+
+julia> Pkg.METADATA_compatible_uuid("MyPackage")
+UUID("b4f0291d-fe17-52bc-9479-3d1a343d9043")Adding members
Add members with the corresponding access rights under Settings/Manage access.
Protecting branches
Add rules for branch protection under Settings/Branches for the master and gh-pages branches (copy them from an existing repository).
Publishing packages
- Install JuliaTeam Registrator (under Settings/Integrations & services).
- Copy the file
.github/workflows/TagBot.ymlfrom an existing repository.
Reduce repository size
The page https://github.com/settings/repositories lists each repo size.
To cleanup past docs preview folders, see clean-gh-pages.yml.
That works but it only removes the last preview for the current PR. And if the PR is closed before the preview is pushed, that run errors and does not remove the folder. To remove all previews from the history, one can do this locally:
git checkout gh-pages
+git rm -rf "previews/PR*"
+git commit -m "delete previews"
+git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+git push --force origin gh-pages-new:gh-pages
+git checkout master
+git branch -D gh-pages gh-pages-newSomething that can also help to shrink the local git size (especially after this change): git gc.
Settings
This document was generated with Documenter.jl version 1.3.0 on Monday 8 April 2024. Using Julia version 1.10.2.
Releases and bots
This is a short step-by-step manual on how to make a new release of a package. In the process of maintaining a package, updating dependencies, etc., there are some "bots" (services) that are commonly used in Julia projects. Those are also mentioned in this section.
Choosing a new release version
First you have to choose whether you want to create a patch release, a minor release, or a major release.
- Major releases are very rare cases for major breaking changes in the API, which should typically be avoided.
- Minor releases are used when some dependency has changed (e.g., a new dependency was added), a mild breaking change in the API was added, or some important feature was added.
- Patch releases are used for everything else.
For more information, check Semantic Versioning.
Preparing the release
Edit the file Project.toml and change the version number of the package to the new version. Make a new pull request and wait until CI passes and the PR gets merged.
Creating a new release
Choose the appropriate subsection for this step and locate the release notes. Usually we keep the release notes in the wiki part of the project ("Release-log tracker"). These release notes correspond to the development version of the package until the next release.
Creating a new release on General (Julia ecosystem packages only)
If the package is released in the Julia ecosystem, a pull request to General has to be made to make new versions available. Registrator is used for this purpose. Find the issue named Releases in the issue tracker and write the following comment.
@JuliaRegistrator register()This will let Registrator trigger a pull request to General. Check that everything works there and then wait until the pull request gets merged. Then the TagBot will create a new release on Github. Finally, you need to manually write the release notes for that release.
Creating a new release on Github
If the package is not released in the Julia ecosystem, you can just manually create a release on Github with the corresponding release notes.
Clean up the release log
Finally, remove the items from the release log in the wiki (keep the headlines, though).
Compatibility bot
The Julia package CompatHelper.jl can be used to automatically update the [compat] entries for your Julia package's dependencies. It is easy to install; just create and edit the file .github/workflows/CompatHelper.yml as described in CompatHelper.jl's documentation. Once installed, this github action will automatically create PRs to update compatibility bounds of the dependencies of the package.
Registrator bot
The Registrator.jl bot is a github app that automates creation of registration pull requests for your Julia packages to the General registry. To install, just click on the installation button that can be found on Registrator.jl's documentation. Once installed, the usual procedure to register a new release is:
The procedure for registering a new package is the same as for releasing a new version.
Set your project's
Project.tomlversion field in your repository to your new desired version.Comment
@JuliaRegistrator registeron the commit/branch you want to register.Either rely on the TagBot GitHub Action to tag and make a github release automatically (recommended, see Tag bot below) or alternatively tag the release manually.
Tag bot
The TagBot github action is used to automatically create tags, releases, and changelogs for your Julia packages when they're registered. It is easy to install; just create and edit the file .github/workflows/TagBot.yml as described in TagBot's documentation. Once installed, this github action will automatically create a release and tag a release log each time the package was registered using JuliaRegistrator @register.
Settings
This document was generated with Documenter.jl version 1.3.0 on Monday 8 April 2024. Using Julia version 1.10.2.
![](\"path/to/image.png\")
","category":"page"},{"location":"guidelines/#Other-style-guides","page":"Coding guidelines","title":"Other style guides","text":"","category":"section"},{"location":"guidelines/","page":"Coding guidelines","title":"Coding guidelines","text":"Below we list other Julia code style guides that we have found interesting.","category":"page"},{"location":"guidelines/","page":"Coding guidelines","title":"Coding guidelines","text":"Yet Another Style Guide For Julia\nJuMP.jl style guide\nJulia style guide\nColPrac – Describes some best practices for collaborating on repositories. Following these practices makes it easier for contributors (new and old) to understand what is expected of them.","category":"page"},{"location":"#JuliaReachDevDocs","page":"Home","title":"JuliaReachDevDocs","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"JuliaReachDevDocs hosts resources for the JuliaReach github organization developers.","category":"page"},{"location":"#Contents","page":"Home","title":"Contents","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Pages = [\n \"index.md\",\n \"newpkg.md\",\n \"release.md\",\n \"guidelines.md\"\n]\nDepth = 3","category":"page"}]
+}
diff --git a/previews/PR56/siteinfo.js b/previews/PR56/siteinfo.js
new file mode 100644
index 0000000..388bc41
--- /dev/null
+++ b/previews/PR56/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR56";
diff --git a/previews/PR56/workflow/index.html b/previews/PR56/workflow/index.html
new file mode 100644
index 0000000..79c24dc
--- /dev/null
+++ b/previews/PR56/workflow/index.html
@@ -0,0 +1,19 @@
+
+Git workflow
This page contains some general information about the recommended workflow to develop JuliaReach projects and some frequently asked questions & git workflow tips.
Branches and pull requests (PR)
We use a standard pull request policy: You work in a private branch and eventually add a pull request, which is then reviewed by other programmers and merged into the master branch.
Each pull request should be pushed in a new branch with the name of the author followed by a descriptive name, e.g., mforets/my_feature. If the branch is associated to a previous discussion in one issue, we use the name of the issue for easier lookup, e.g., mforets/7.
Unit testing and continuous integration
This project is synchronized with GitHub Actions such that each PR gets tested before merging (and the build is automatically triggered after each new commit). For the maintainability of this project, it is important to make all unit tests pass.
To run the unit tests locally, you can do:
julia> using Pkg
+
+julia> Pkg.test("MathematicalSets")We also advise adding new unit tests when adding new features to ensure long-term support of your contributions.
Contributing to the documentation
New functions and types should be documented according to our guidelines directly in the source code.
You can view the source code documentation from inside the REPL by typing ? followed by the name of the type or function. For example, the following command will print the documentation of the AbstractSet type:
julia> ?AbstractSetThis documentation you are currently reading is written in Markdown, and it relies on Documenter.jl to produce the HTML layout. The sources for creating this documentation are found in docs/src. You can easily include the documentation that you wrote for your functions or types there (see the Documenter.jl guide or our sources for examples).
To generate the documentation locally, run make.jl, e.g., by executing the following command in the terminal:
$ julia --color=yes docs/make.jlNote that this also runs all doctests which will take some time.
Reviewing a pull request from a fork
To pull a PR numbered x from a fork, do
$ git fetch origin pull/x/head:pr/x && git checkout pr/xContributing from a fork
It is not uncommon that user A wants to contribute to package X and A doesn't have write access to X. In that case, the usual procedure is that A creates a fork of X, and then creates a PR to be merged by the maintainer of package X. You have to properly setup the branches to do so:
origin– is usually set to the fork of the projectupstream– is usually set to the main project
For example, suppose that user mforets would like to setup the package Polyhedra working from a fork. The git command git remote -v prints all the remote repositories, and you can modify them with git remote add to add a new one and git remote set-url to change the URL of an existing repository (it is also possible to manually edit the file .git/config). In the example:
[mforets@localhost dev]$ cd Polyhedra
+
+[mforets@localhost Polyhedra]$ git remote -v
+origin https://github.com/JuliaPolyhedra/Polyhedra.jl.git (fetch)
+origin https://github.com/JuliaPolyhedra/Polyhedra.jl.git (push)
+
+[mforets@localhost Polyhedra]$ git remote add upstream https://github.com/JuliaPolyhedra/Polyhedra.jl.git
+
+[mforets@localhost Polyhedra]$ git remote set-url origin https://github.com/mforets/Polyhedra.jl.git
+
+[mforets@localhost Polyhedra]$ git remote -v
+origin https://github.com/mforets/Polyhedra.jl.git (fetch)
+origin https://github.com/mforets/Polyhedra.jl.git (push)
+
+upstream https://github.com/JuliaPolyhedra/Polyhedra.jl.git (fetch)
+upstream https://github.com/JuliaPolyhedra/Polyhedra.jl.git (push)Editors
There is no official IDE for Julia. For those using the Atom editor, there are several plugins for Julia development, among them:
- language-julia – code highlighting, etc.
- language-markdown – support for Markdown files
- latex-completions – auto-completions, eg. for LaTeX symbols as in
\alpha[TAB]that prints α - markdown-preview-plus – preview Markdown files
- platformio-ide-terminal – terminal embedded in the editor
Settings
This document was generated with Documenter.jl version 1.3.0 on Monday 8 April 2024. Using Julia version 1.10.2.