How to use this documentation

This documentation is generated using Jupyter books. You can learn more about the project on their website.

Structure and navigation

Close the left hand side bar by clicking the left facing arrow in the top panel.

You can close the left hand side bar by clicking the left facing arrow in the top panel. This increases the width of the middle section of the documentation and can be helpful on smaller screens. You can click the hamburger menu that replaces the left facing arrow to open the left hand side bar when required.

The documentation is divided into a few parts that can be seen in the left hand side navigation bar:

  • User documentation: this includes documentation for anyone looking to use NeuroML

  • NeuroML events: any events related to NeuroML will be listed here

  • The NeuroML Initiative: this includes documentation on the NeuroML community

  • Developer documentation: this includes information for individuals looking to contribute to NeuroML (either the standard or the software)

  • Reference: this includes the glossary of terms and the bibliography.

Each part contains different chapters, which can each contain different sections. Each page in the documentation also has its own navigation in the right hand side bar.

Using Jupyter books included in the documentation

Familiar with Jupyter Notebooks, skip ahead to the next section.

If you are familiar with Jupyter Notebooks, you can skip ahead to the Getting started with NeuroML section.

The most important feature of Jupyter books is that it allows you to include Jupyter notebooks in the documentation. This allows us to write documentation which includes code examples that can be modified and executed by users interactively in their browsers without having to install anything on their local machines. For example, these are used in the Getting Started section.

Each Jupyter notebook in the documentation includes a rocket icon 🚀 in the top bar:

Click the rocket icon in top panel of executable pages to execute them in Binder or Google Collaboratory.

Fig. 1 Click the rocket icon in top panel of executable pages to execute them in Binder or Google Collaboratory.

Clicking this icon will allow you to run the Jupyter Notebook:

You can run the Jupyter Notebook on Binder or Google Colaboratory.

Fig. 2 You can run the Jupyter Notebook on Binder or Google Colaboratory.

You can choose from freely available services such as Binder and Google Colaboratory. Both Binder and Google Colaboratory will take you to these services and load the Jupyter Notebook for you to use. The Live code option uses Binder but allows you to run the code in the current tab itself. However, please note that this option does not include the full Jupyter Notebook features that Binder and Google Colaboratory provide.

Run Binder and Google Colaboratory in a new tab.

It is suggested to right click and select “Open in new tab” so that the tab with the NeuroML documentation remains open. In most browsers, you can also use Ctrl + click to open links in a new tab:

Izhikevich example running in Binder.

Fig. 3 Izhikevich example running in Binder

Izhikevich example running in Google Colaboratory.

Fig. 4 Izhikevich example running in Google Colaboratory.

Izhikevich example running on Binder but using the Live Code option.

Fig. 5 Izhikevich example running in Binder but using the Live Code option.

When running the Jupyter notebooks using these services, you can make changes to the code and re-run it as required. On Binder and Google Colaboratory, which provide the full range of Jupyter Notebook features, you can also run all the code cells at once in sequence. Please see the documentation pages to learn more about using Binder and Google Colaboratory here and here respectively. General information on using Jupyter Notebooks and the interface can be found in the documentation here.

Downloading Jupyter Notebooks to run locally on your machine

Jupyter Notebooks can also be downloaded and run locally on your machine. To download the notebooks, use the Download link in the top panel:

Jupyter notebooks can be downloaded using the Download link in the top panel.

Fig. 6 Jupyter notebooks can be downloaded using the Download link in the top panel.

You will need to install the Python Jupyter Notebook packages to do so. Please refer to the Jupyter Notebook documentation to see how you can install Jupyter Notebooks. Additionally, you will also need to install the NeuroML software to run these notebooks. Information on using Jupyter Notebooks and the interface can be found in the documentation here.

Reporting bugs and issues

Please report any issues that you may find in the documentation so that it can be improved. To report an issue on a particular page, you can use the “open issue” link under the GitHub icon in the top panel. Additionally, you can also suggest edits by editing the page in a fork and opening a pull request using the “suggest and edit” link.

You can report issues and suggest edits to the documentation to help us improve it using the options in the GitHub icon in the top panel.

Fig. 7 You can report issues and suggest edits to the documentation to help us improve it using the options in the GitHub icon in the top panel.

You can also always contact the NeuroML community using our communication channels if required.