Merge pull request #101 from NeuralEnsemble/fix/update-docs

Update documentation

doc/api.rst

@@ -0,0 +1,13 @@
+API documentation
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   coreclasses
+   loaders
+   writers
+   utils
+   arraymorph
+
+

doc/arraymorph.rst

@@ -0,0 +1,10 @@
+
+:mod:`arraymorph` Module
+------------------------
+
+.. automodule:: neuroml.arraymorph
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+

doc/bibliography.rst

@@ -0,0 +1,5 @@
+References
+==========
+
+.. bibliography::
+   :all:

doc/conf.py

@@ -11,7 +11,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
 
 # 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
@@ -28,13 +29,19 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
+              'sphinxcontrib.bibtex']
+
+bibtex_bibfiles = ['refs.bib']
+
+# Include TODOs in docs
+todo_include_todos = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
-source_suffix = '.txt'
+source_suffix = '.rst'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -44,16 +51,19 @@
 
 # General information about the project.
 project = u'libNeuroML'
-copyright = u'2017, libNeuroML authors and contributors'
+copyright = u'2021, libNeuroML authors and contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-for l in open('../neuroml/__init__.py'):
-    if '__version__' in l:
-        version = l.split("'")[1]
+version = ""
+for aline in open('../neuroml/__init__.py'):
+    # space here is important since __version__ is used in generation of
+    # version_info also
+    if '__version__ =' in aline:
+        version = aline.split("'")[1]
 # The full version, including alpha/beta/rc tags.
 release = version
 
@@ -115,7 +125,7 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = 'neuroml_logo.png'
+html_logo = '_static/neuroml_logo.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -174,7 +184,6 @@
 
 # -- Options for LaTeX output --------------------------------------------------
 
-latex_elements = {
 # The paper size ('letterpaper' or 'a4paper').
 #'papersize': 'letterpaper',
 
@@ -183,13 +192,13 @@
 
 # Additional stuff for the LaTeX preamble.
 #'preamble': '',
-}
+latex_elements = {}
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'libNeuroML.tex', u'libNeuroML Documentation',
-   u'libNeuroML authors and contributors', 'manual'),
+    ('index', 'libNeuroML.tex', 'libNeuroML Documentation',
+     'libNeuroML authors and contributors', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -218,8 +227,8 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'libneuroml', u'libNeuroML Documentation',
-     [u'libNeuroML authors and contributors'], 1)
+    ('index', 'libneuroml', 'libNeuroML Documentation',
+     ['libNeuroML authors and contributors'], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -232,9 +241,9 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'libNeuroML', u'libNeuroML Documentation',
-   u'libNeuroML authors and contributors', 'libNeuroML', 'One line description of project.',
-   'Miscellaneous'),
+    ('index', 'libNeuroML', 'libNeuroML Documentation',
+     'libNeuroML authors and contributors', 'libNeuroML', 'This package provides libNeuroML for working with neuronal models specified in NeuroML 2.',
+     'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.

doc/neuroml.nml.txt → doc/coreclasses.rst

@@ -1,10 +1,5 @@
-NeuroML core classes
-====================
-
-
-
-:mod:`nml` Module
------------------------------
+:mod:`nml` Module (NeuroML Core classes)
+-----------------------------------------
 
 Note: This module is included in the top level of the `neuroml` package, so you can use these classes by importing neuroml:
 
@@ -14,5 +9,6 @@ Note: This module is included in the top level of the `neuroml` package, so you
 
 .. automodule:: neuroml.nml.nml
     :members:
-    :show-inheritance:
+
+
 

doc/how_to_contribute.rst

@@ -0,0 +1,113 @@
+How to contribute
+=================
+
+libNeuroML development happens on GitHub, so you will need a GitHub account to contribute to the repository.
+Contributions are made using the standard `Pull Request`_ workflow.
+
+Setting up
+----------
+
+Please take a look at the GitHub documentation here: http://help.github.com/fork-a-repo/
+
+To begin, please fork the repo on the GitHub website.
+You should now have a libNeuroML under you username.
+Next, we clone our fork to get a local copy on our computer:
+
+::
+
+    git clone [email protected]:_username_/libNeuroML.git
+
+While not necessary, it is good practice to add the upstream repository as a remote that you will follow:
+
+::
+
+    cd libNeuroML
+    git remote add upstream https://github.com/NeuralEnsemble/libNeuroML.git
+    git fetch upstream
+
+
+You can check which branch are you following doing:
+
+::
+
+    git branch -a
+
+You should have something like:
+
+::
+
+    git branch -a
+    * master
+      remotes/origin/HEAD -> origin/master
+      remotes/origin/master
+      remotes/upstream/master
+
+
+Sync with upstream
+------------------
+
+Before starting to do some work, please check to see that you have the latest copy of the sources in your local repository:
+
+::
+
+    git fetch upstream
+    git checkout development
+    git merge upstream/development
+
+Working locally on a dedicated branch
+-------------------------------------
+
+Now that we have a fork, we can start making our changes to the source code.
+The best way to do it is to create a branch with a descriptive name to indicate what are you working on.
+Generally, your will branch off from the upstream `development` branch, which will contain the latest code.
+
+For example, just for the sake of this guide, I'm going to work on issue #2.
+
+::
+
+    git checkout development
+    git checkout -b fix-2
+
+
+We can work in this branch, and make as many commits as we need to:
+
+::
+
+    # hack hack hack
+    git commit -am "some decent commit message here"
+
+
+Once we have finished working, we can push the branch online to our fork:
+
+::
+
+   git push origin fix-2
+
+
+We can then open a pull-request to merge our ``fix-2`` branch into ``upstream/development``.
+If your code is not ready to be included, you can update the code on your branch and any more commits you add there will be added to the Pull Request.
+Members of the libNeuroML development team will then discuss your changes with you, perhaps suggest tweaks, and then merge it when ready.
+
+Continuous integration
+-----------------------
+
+libNeuroML uses continuous integration (`Wikipedia <https://en.wikipedia.org/wiki/Continuous_integration>`_).
+Each commit to the master or development branches is tested, along with all commits to pull requests.
+The latest status of the continuous integration tests can be seen `here on GitHub Actions <https://github.com/NeuralEnsemble/libNeuroML/actions>`_.
+
+Release process
+---------------
+
+libNeuroML is part of the official NeuroML release cycle.
+When a new libNeuroML release is ready the following needs to happen:
+
+- Update version number in setup.py
+- update version number in doc/conf.py
+- update release number in doc/conf.py (same as version number)
+- update changelog in README.md
+- merge development branch with master (This should happen via pull request - do not do the merge yourself even if you are an owner of the repository.
+- push latest release to PyPi
+
+More information on the NeuroML release process can be found on the `NeuroML documentation page <https://docs.neuroml.org/Devdocs/ReleaseProcess.html>`_.
+
+.. _Pull Request: http://help.github.com/send-pull-requests/