For developers

We provide both NERDSS and ioNERDSS as open-sourced programs. We welcome users to help us develop both programs!

The codes for NERDSS is available on our github repository. To modify it, simply fork it to your github account and make pull requests to have your edits be incorporated in NERDSS.

We also welcome users to develop ioNERDSS with us! If you created functions that you find useful in asisting NERDSS simulation, it is our pleasure to include your functions in ioNERDSS. Just follow the instructions in the ioNERDSS Developer's Guide below to get started:

1. Sign up on Pypi and Join as Collaborators

For the first-time user, register an account on Pypi (https://pypi.org), search for the ioNERDSS library, and request to join as a collaborator. This will usually require authorization from the ioNERDSS library owner Margaret Johnson (margaret.johnson@jhu.edu).

2. Update Files for ioNERDSS Library

All files of the ioNERDSS library are stored in the io_nerdss repository on Github (https://github.com/mjohn218/io_nerdss) under the ioNERDSSLibrary folder. To update the ioNERDSS library, three main files will be modified:

2.1 Modify init.py

Located at /GitHub/io_nerdss/ioNERDSSLibrary/ioNERDSS/init.py, this file stores all the functions included in ioNERDSS. Modify this file if more features need to be added or if existing functions need changes. The file should only contain function definitions, without running code.

2.2 Modify CHANGELOG.txt

Located at /GitHub/io_nerdss/ioNERDSSLibrary/CHANGELOG.txt, this file records the changes in each version update along with the version number. Record change information and the version number here in a contextual format.

2.3 Modify setup.py

Located at /GitHub/io_nerdss/ioNERDSSLibrary/setup.py. Update the version variable in the setup function to the new version number.

3. Generate Distribution Files

First-time users should ensure that the latest versions of setuptools and wheel are installed. Run the following command in the system command line:

python3 -m pip install --user --upgrade setuptools wheel

To check setup.py for errors, use this command:

python setup.py check

If no errors are found, pack the library’s source code by running this command in the ioNERDSSLibrary folder:

python setup.py sdist build

A .tar.gz file of the current version will be added to the dist folder.

4. Update Package to Pypi

First-time users need to install twine by running:

pip install twine

After installation, run this command in the ioNERDSSLibrary folder to upload the library. You will be prompted for your registered Pypi username and password:

twine upload dist/*

After upload, the new version of the ioNERDSS library will appear on the Pypi website for a final check: https://pypi.org/project/ioNERDSS/.

Once updated, remember to push the latest original files into the io_nerdss repository on Github.

We kindly ask you to follow the best practices while developing your functions:

  • Use docstrings to document your code. Sphinx can extract docstrings from your code to create documentation, so it's important to write clear and concise docstrings that describe the purpose and functionality of your code.
  • Use reStructuredText (reST) markup in your docstrings.
  • Follow the Google-style docstring conventions. This is a popular convention for writing docstrings that is widely used in the Python community. It consists of a one-line summary, followed by a more detailed description, and optional sections for parameters, returns, and other details. You can find more information on this convention in the Sphinx documentation.
  • Organize your code into modules and packages.
  • Use meaningful names for modules, classes, functions, and variables.
  • Include examples and usage instructions in documentation. Sphinx can include examples and usage instructions in your documentation, which can help users understand how to use your code.
  • Use Sphinx to generate documentation.
  • Add tests for each function using unittest.