Contributing

Legolas is developed as an open-source code, which means that we welcome contributions that improve the code in any way. The ideal way to do this is following a proper GitHub workflow. This means that you first fork the main Legolas repository, make the edits you want and then submit a pull request. Since everything is contained in the main repository you can edit the Legolas source code, the docs or the Pylbo source code this way.

Once the pull request (PR) is submitted it will be up for review by one of the main developers. Please make use of the dedicated labels to label your pull request (or issue), this allows us to easily keep track of the various types of additions that are being made.

Note: all PR’s should be directed against the develop branch, and NOT against the master branch. We keep the master branch dedicated to stable releases, and keep “new” features on the develop branch until we release a new major/minor version. Doc updates are an exception to this, since the website is built from the master branch.

Adding to the Legolas code

For contributions to the Legolas source code we have the following guidelines:

  • Variable names should be self-explanatory but consistent (with the exception of parameters)
  • When printing information to the console, make use of the dedicated logging module, in particular the log_message() subroutine.
  • New features should go in dedicated (sub)modules if possible.
  • Consistent indentation across the entire code and free-format syntax.
  • In the case of new subroutines: add a test to the core tests
  • In the case of new equilibria: add a test to the regression tests

Important:
Every new bit of code has to be supplemented by corresponding documentation, which should be clear and concise. For Legolas docstrings we use FORD syntax, take a look at the already documented modules for more information and examples.

Adding to the Pylbo code

For contributions to the Pylbo source code there are no “real” guidelines, besides the regular Python guidelines. This means that all new or modified code should follow the PEP8 guidelines (roughly). An exception to this is the maximum line length, since Black uses 88 (instead of the 79 suggested by PEP). Method names are also quite flexible, if they are concise and clear it’s fine.

Additionally, whenever you add code you should also add a dedicated unit test to the pylbo tests.

Important:
Every new bit of code has to be supplemented by corresponding documentation, which should be clear and concise. For Pylbo docstrings we use Sphinx syntax, supplemented by the NumPy docstring convention. Take a look at the already documented methods and classes for more information and examples

Adding to the documentation

Edits to the website

The documentation (this website) is built from the docs folder on the master branch, using GitHub Pages. We make use of Jekyll and the minimal-mistakes theme. For instructions and detailed guides we refer back to those pages.

When making edits to the documentation it is a good idea to compile it locally before pushing to the repository, that way you avoid small mistakes like broken links and incorrect formatting. You need a Ruby development environment for this, instructions are given on the Jekyll website. We’ll sum them up below:

  • Ruby version 2.5.0 or higher, you can check through ruby -v
  • RubyGems, you can check through gem -v
  • GCC and Make, you can check through gcc -v, g++ -v and make -v.

Once you have this set up, you install the Jekyll and Bundler Gems

gem install jekyll bundler

and that’s it! Now you simply navigate to the docs folder and type

bundle exec jekyll serve

after which the website builds in a folder _site, and it will tell you the local URL that you can paste in your browser of choice (denoted by “Server address). Due to the serve statement you can make additional edits to the documentation and refresh the webpage to immediately look at the result.

Edits to the Pylbo docs

For the pylbo docs you’ll need Sphinx configured, together with its dependencies. You can install all of them through the install_dependencies.sh script in the docs folder:

sh install_dependencies.sh

or, if you want to do it manually:

pip install -U sphinx
pip install numpydoc
pip install sphinx-rtd-theme
pip install lazy-object-proxy==1.4
pip install sphinx-autoapi

Once this is done, you can execute

sh build_sphinx.sh

to build the Sphinx documentation, which is configured in such a way that Jekyll finds the generated html files.

Edits to the Legolas docs

For the Legolas docs you’ll need Ford. The install_dependencies.sh script installs it together with the Sphinx dependencies, but just in case you want to do it manually:

pip install ford

Once this is done, you can execute

ford build_ford.md

to build the Ford documentation, which is configured in such a way that Jekyll finds the generated html files.