Merge pull request #189 from NeuralEnsemble/experimental

feat!: regenerate for 2.3.1

Author: pgleeson

.github/workflows/ci.yml

@@ -39,7 +39,7 @@ jobs:
       if: ${{ matrix.runs-on == 'macos-latest' }}
       run: |
         brew install hdf5
-        
+
     - name: Build package
       run: |
         pip install .[full]

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-added-large-files
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.4.1
+  hooks:
+    - id: ruff
+      args: [ "--select", "I", "--fix" ]
+    - id: ruff-format

CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# Contributing
+
+Please open issues to discuss enhancements and bugs that you may encounter with
+libNeuroML. Pull requests with enhancements and bug fixes are welcome.
+
+## Virtual environments and editable installs
+
+It is best to use [virtual environments](https://docs.python.org/3/tutorial/venv.html) when developing Python packages.
+This ensures that one uses a clean environment that includes the necessary
+dependencies and does not affect the overall system installation.
+
+For quick development, consider using [editable installs](https://setuptools.pypa.io/en/latest/userguide/development_mode.html).
+The dependencies are broken down in the `setup.cfg` file. To get a complete development environment, one can run:
+
+
+    pip install -e .[dev]   # an editable install with all development dependecies installed
+
+
+## Code style
+
+1. The source code uses spaces, and each tab is equivalent to 4 spaces.
+
+2. We use the [reStructuredText (reST)
+   format](https://stackoverflow.com/a/24385103/375067) for Python docstrings.
+   Please document your code when opening pull requests.
+   All methods/functions/modules *must* include docstrings that explain the parameters.
+
+3. We use [ruff](https://pypi.org/project/ruff/) to format and lint our code. (See the section on pre-commit below.)
+
+4. Please use [type hints](https://docs.python.org/3/library/typing.html) wherever applicable.
+   You can set up type checkers such as [mypy](https://mypy.readthedocs.io/) to use type hints in your development environment/IDE.
+
+
+        pip install mypy
+
+
+### Pre-commit
+
+A number of [pre-commit](https://pre-commit.com/) hooks are used to improve code-quality.
+Please run the following code to set up the pre-commit hooks:
+
+    $ pre-commit install
+
+The hooks will be run at each `git commit`.
+Please see `.pre-commit-config.yaml` for information on what hooks we run.
+
+
+### Commit messages
+
+Writing good commit messages makes things easy to follow.
+Please see these posts:
+
+- [How to write a Git commit message](https://cbea.ms/git-commit/)
+- While not compulsory, we prefer [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
+
+
+## Tests
+
+Bug fixes and new features should include unit tests to test for correctness.
+One can base new tests off the current ones included in the `tests/` directory.
+To see how tests are run, please see the [GitHub Actions configuration file](https://github.com/NeuralEnsemble/libNeuroML/blob/development/.github/workflows/ci.yml).
+
+We use [pytest](https://docs.pytest.org/) for unit testing.
+One can run it from the root of the repository:
+
+    pytest
+
+
+To run specific tests, one can use the `-k` flag:
+
+
+    pytest -k "..."
+
+
+## Pull Request Process
+
+1. Please contribute pull requests against the `development` branch.
+2. Please ensure that the automated build for your pull request passes.
+3. Please write good commit messages (see the section above).
+
+### Updating your pull request branch
+
+Over time, as pull requests are reviewed, the `development` branch continues to move on with other changes.
+Sometimes, it can be useful/necessary to pull in these changes to the pull request branch, using the following steps.
+
+Add the upstream libNeuroML repository as a remote:
+
+
+    git remote add upstream https://github.com/NeuralEnsemble/libNeuroML.git
+
+
+Update your local copy of the `development` branch, and the remote copy in your fork:
+
+
+    git checkout development
+    git pull upstream development
+    git push
+
+
+Pull in changes from development to your branch:
+
+
+    git checkout <feature branch being used for PR>
+    git merge development
+
+
+If there are merge conflicts, you will need to [resolve these](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#_basic_merge_conflicts), since merging the feature branch in the pull request will also result in these.
+After any merge conflicts have been resolved (or if there aren't any), you can
+push your branch to your fork to update the pull request:
+
+
+    git push

doc/conf.py

@@ -11,8 +11,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
+import sys
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the

doc/devdocs/index.rst

@@ -9,4 +9,3 @@ Contributing
    implementation_of_bindings
    meeting_june_2012
    nodes_segments_sections
-

doc/devdocs/meeting_june_2012.rst

@@ -109,7 +109,7 @@ Mike V was asked to add a clone method to a morphology.
 It was decided that fraction_along should be a property of segment.
 
 The syntax for segment groups should be as follows:
-group=morph.segment_groups['axon_group'] 
+group=morph.segment_groups['axon_group']
 (in connect merge groups should be false by default - throw an exception, tell the user setting merge_groups = True or rename group will fix this)
 
 This was a subject of great debate and has not been completely settled.

doc/devdocs/nodes_segments_sections.rst

@@ -58,7 +58,7 @@ unbranched segmentGroups, which can be used as the basis for sections in any par
 in them, or be ignored by any other application.
 
 In libNeuroML, a section-like concept can be added at API level, to facilitate building cells, to facilitate import/export
-to/from simulators supporting this concept, and to serve as a basis for recompartmentalisation of cells. 
+to/from simulators supporting this concept, and to serve as a basis for recompartmentalisation of cells.
 
 
 
@@ -96,7 +96,7 @@ to the **parent** element, i.e.
     <parent segment="2" fractionAlong="0.5"/>
 
 This is not possible in a node based format, but represents a logically consistent description of what the modeller
-wants. 
+wants.
 
 
 What to do?
@@ -108,4 +108,4 @@ enforce "best practice"?
 PG: I'd argue for the first approach, as it retains as much as possible of what the original reconstructor/simulator specified.
 An API which enforces a policy when it encounters a non optimal morphology (e.g. moving all dendrites to connection points,
 inserting new nodes) will alter the original data in perhaps unintended ways, and that information will be lost by subsequent readers.
-It should be up to each parsing application to decide what to do with the extra information when it reads in a file.
+It should be up to each parsing application to decide what to do with the extra information when it reads in a file.

doc/helpers/nml-core-docs.py

@@ -7,7 +7,6 @@
 Copyright 2023 NeuroML authors
 """
 
-
 import textwrap
 
 print("Generating list of nml classes")

doc/refs.bib

@@ -20,4 +20,3 @@ @Article{Vella2014
   timestamp    = {2019-02-20},
   year         = {2014},
 }
-

doc/userdocs/api.rst

@@ -12,5 +12,3 @@ You can find information on these in the pages below.
    writers
    utils
    arraymorph
-
-