Commands¶

The commands below do not belong to a package (although they are listed with the prefix root.). They can be found either in the RepLAB root or src folders.

replab_Version¶

class root.replab_Version(major, minor, patch, snapshot)¶

Describes and manipulates RepLAB version identifiers

This file is also used by replab_init to check whether the RepLAB source folder is already in the path.

Class members list

Properties

major – integer: Major version index
minor – integer: Minor version index
patch – integer: Patch version index
snapshot – logical: Is the version a snapshot

General

asRelease –
asSnapshot –
bumpMajor –
bumpMinor –
bumpPatch –
current –
disp –
fromText – Parses a version string and creates a replab_Version object
fromVersionFile – Create a replab_Version object from the replab_version.txt text file
incrementedMajor –
incrementedMinor –
incrementedPatch –
prompt –
replab_Version –
setTo –
tag –
toText –
updateVersionFile –

Inherited elements

asRelease()¶: No documentation

asSnapshot()¶: No documentation

bumpMajor()¶: No documentation

bumpMinor()¶: No documentation

bumpPatch()¶: No documentation

current()¶: No documentation

disp()¶: No documentation

incrementedMajor()¶: No documentation

incrementedMinor()¶: No documentation

incrementedPatch()¶: No documentation

prompt()¶: No documentation

replab_Version()¶: No documentation

setTo()¶: No documentation

tag()¶: No documentation

toText()¶: No documentation

updateVersionFile()¶: No documentation

Own members

major¶: integer: Major version index

minor¶: integer: Minor version index

patch¶: integer: Patch version index

snapshot¶: logical: Is the version a snapshot

static fromText(txt)¶

Parses a version string and creates a replab_Version object

In case of a parse error, returns []

static fromVersionFile()¶: Create a replab_Version object from the replab_version.txt text file

replab_init¶

root.replab_init(varargin)¶

Sets up the search path in order to enable all functionalities of the RepLAB library.

You can call “replab_init” repeatedly without any problem. The first call initializes the library, and the second and subsequent calls detect that the library is initialized and bail out early.

However, you need to call “replab_init” again after doing a “clear all”.

Also verifies that a SDP solver is available, installs and registers the bundled SDPT3 solver if needed, and initializes important variables.

The global variable replab.globals.replabPath is set up and mlock-ed so that it persists a clear all.

This script accepts the following options:

The key verbose followed by a value 0,1,2, controls the display level when initializating
- 0: only produce a display in case of error/warning or for critical cases
- 1: informs of the changes made (default value)
- 2: prints full information
The option autoinstall: Install dependencies automatically
The option showurls: Shows the URL that need to be downloaded to activate dependencies

Parameters: varargin (cell(1,*) of key/value pairs) – Options, see description above

Example

>>> replab_init   % doctest: +SKIP
    Adding RepLAB to the path
    Adding VPI to the path
    Adding MOxUnit to the path
    Adding embedded YALMIP to the path

replab_checkhelp¶

root.replab_checkhelp()¶

Checks the soundness of documentation comments

Returns: True if no problems were detected
Return type: logical

replab_checkoop¶

root.replab_checkoop()¶

Checks the object oriented programming structure of the code

The main reason for this function is the fact that inheritance rules are a bit different between Matlab and Octave.

This includes two kinds of checks, performed one after the other one upon success:

1. Check that inherited methods admit only one possible implementation. When inheriting from multiple classes, a given method can be provided several definitions. Since Matlab and Octave use different rules to choose which definition to use (and some of these rules might evolve in the future), we check here that no such situation arises. This is needed to guarantee that the same code is provided to both interpreters.

2. When the first test passes, this function also checks that all classes which are not inherited by any other class contain no ‘Abstract’ method, i.e. that no top class is abstract.

Aditionally, we could also check that all references to replab objects in the code point to an existing definition (similarly to what replab_checkhelp does for the documentation).

Returns: True if no problems were detected
Return type: logical

replab_generate¶

root.replab_generate(what)¶

Code generation function

Depending on the value of the argument what:

clear clears out all directories with autogenerated code
doctests extracts the doctests from the source code and writes them to the doctests code folder.
notebooktests extracts the jupyter notebooks from the doc and write them to the notebooks code folder
all regenerates all code

Parameters: what ({'clear', 'doctests', 'notebooks', 'all'}, optional) – What to generate, default 'all'
Returns: True unless an error was detected
Return type: logical

replab_sphinx¶

root.replab_sphinx(what, varargin)¶

Documentation generation function

Depending on the value of the argument what:

clear clears out all directories with autogenerated doc
ppdoc only pre-processes the Sphinx documents
ppsrc only pre-processes the src folder
preprocessing calls successively ppdoc and ppsrc
build only runs the Sphinx documentation generation
all regenerates all documentation by calling successively preprocessing and build
doublePass performs a double build: the first run creates an up to date inventory file, which is then use in the second round. This ensures that all links in the documenttion are up to date with the current API. In case the keyword argument srcFolder is erased, there is no code inventory to build, so this is identical to all (i.e. single pass only).

By default,

Parameters

what ({'clear', 'ppdoc', 'ppsrc', 'preprocessing', 'build', 'all', 'doublePass'}, optional) – What to generate, default 'all'
sphinxRoot – location of the sphinx folder, default is [replab.globals.replabPath, ‘/sphinx’]
preprocessedFolder – folder for temporarily generated files, default is [replab.globals.replabPath, ‘/generated’]
sphinxTarget – where compile the documentation to, default is [replab.globals.replabPath, ‘/docs’]
inventoryAddress – either path to the online RepLAB API, or the the local objects.inv file, default is ‘https://replab.github.io/replab’
srcFolder – replab source code folder, empty means none, default is [replab.globals.replabPath, ‘/src’]
additionalSrc – folders containing additional non-packaged replab source files, empty means none, default is {replab.globals.replabPath, [replab.globals.replabPath, ‘/src’]}

Kwtype sphinxRoot

charstring

Kwtype preprocessedFolder

charstring

Kwtype sphinxTarget

charstring

Kwtype inventoryAddress

charstring

Kwtype srcFolder

charstring

Kwtype additionalSrc

cell{1,*} of charstring

Returns

True unless an error was detected

Return type

logical

replab_release¶

root.replab_release()¶

Releases the current develop branch contents as a stable release

This runs the release process to send the current develop branch snapshot to the branch master, taking care of version numbers in the process.

The documentation is no longer generated as we migrated this part to GitHub actions.

This script works fully offline, interactions with the remote repository are done manually by the user.

There are two types of version numbers in RepLAB:

Version numbers ending in -SNAP are snapshot version numbers which are not supposed to be stable: that means different versions of the RepLAB codebase can have the same snapshot number.
Version numbers not ending in -SNAP are stable version numbers, which are in one to one correspondence with a version of the codebase. It may correspond at most to two commits: the stable commit on the develop branch, and the merge commit of it on master.

The master branch has only strictly increasing, stable version numbers. The develop branch has snapshot version numbers, except during the release process when we “stabilize” the version number for one commit.

We assume the following:

The remote origin corresponds to the repository git@github.com:replab/replab.git
The user has run git fetch origin master develop to synchronize the remote content.
The develop branch is checked out in the main worktree, that is in the root RepLAB folder
All of the branches master, develop have their local copy current with the origin remote.

All the points above are checked by the release process, apart from whether the origin remote has been fetched, as this would require a connection to the remote.

The release steps are as follows.

We ask the user to confirm they ran git fetch origin develop master gh-pages.
We verify that all working trees do not have uncommited changes.
We verify that the branches develop and master are in sync with the origin remote. We verify that the submodule commits are in sync with the data in the external/modules.ini file.
We ask the user to confirm the version number of the stable release (by default, the develop -SNAP version with the -SNAP suffix removed), and the number of the next develop version (by default, the current version number with the minor release number incremented, and the -SNAP suffix added).

We set the version number to the stable number in the develop branch.
We run the replab_runtests script. We abort in case of errors.
We run the replab_checkhelp script.
We set the version number of the develop branch to a stable number. We commit the release on the develop branch.
We checkout the master branch, merge the develop branch by fast-forward.
We tag the master HEAD with a version tag of the form vMAJOR.MINOR.PATH, as in v0.5.0, which is the format that GitHub recognizes for releases.
We checkout the develop branch, set the version number to the next snapshot number, and commit.
We output the command that the user should run to push the changes to the remote. In particular, it involves pushing both the master and develop branches, and the release tag.

replab_runtests¶

root.replab_runtests(varargin)¶

Tests the library functionalities.

See the patternsToExclude variable below to exclude files from code coverage.

Parameters

slowtests – Whether to include tests that can possibly take a long time to run
doctests – Whether to include doctests
notebooktests – Whether to run the notebook tests
withCoverage – Whether to activate code coverage

Kwtype slowtests

optional, true

Kwtype doctests

optional, true

Kwtype notebooktests

optional, true

Kwtype withCoverage

optional, false

Results:: logical: True if all tests passed.