Merge pull request #371 from steffengraber/doc-filename-convention

Changed documentation files to make them adhere to documented conventions.

extras/userdoc/md/documentation/README.md

@@ -0,0 +1,18 @@
+# NEST User Documentation in Markdown
+
+This directory contains the NEST user documentation written in markdown.
+These files are the basis of the public site.
+
+Please follow these short authoring instructions: <https://guides.github.com/features/mastering-markdown/>
+
+## Note these conventions
+
+-   Name files with '-' as separator only.
+
+-   Use the atx header style.
+
+        # This is an <h1> tag
+        ## This is an <h2> tag
+        ###### This is an <h6> tag
+
+-   Use relative links regarding the need of GitHub <https://help.github.com/articles/relative-links-in-readmes/>

extras/userdoc/md/documentation/an_introduction_to_sli.md → extras/userdoc/md/documentation/an-introduction-to-sli.md

@@ -1,8 +1,6 @@
-An Introduction to SLI
-======================
+# An Introduction to SLI
 
-Introduction
-------------
+## Introduction
 
 NEST can be started by typing
 
@@ -25,8 +23,7 @@ at the command prompt. You should then see something like this:
     Type 'help' to get more information.
     Type 'quit' or CTRL-D to quit NEST.
 
-Command line switches
----------------------
+## Command line switches
 
 Type
 
@@ -74,13 +71,12 @@ to an integer. Using `mark` and `>>`, the content of the userargs array is added
 to a dictionary, which is stored under the name `args`. The second line just
 prints the content of the lamda variable.
 
-SLI user manual
----------------
+## SLI user manual
 
 This manual gives a brief overview of the SLI programming language.
 
-1.  [First Steps](first_steps.md "First Steps")
-2.  [Objects and data types](objects_and_data_types.md "Objects and data types")
-3.  [Programming in SLI](programming_in_sli.md "Programming in SLI")
-4.  [Using files and keyboard input](using_files_and_keyboard_input.md "Using files and keyboard input")
-5.  [Neural simulations](neural_simulations.md "Neural simulations")
+1.  [First Steps](first-steps.md)
+2.  [Objects and data types](objects-and-data-types.md)
+3.  [Programming in SLI](programming-in-sli.md)
+4.  [Using files and keyboard input](using-files-and-keyboard-input.md)
+5.  [Neural simulations](neural-simulations.md)

extras/userdoc/md/documentation/analog_recording_with_multimeter.md → extras/userdoc/md/documentation/analog-recording-with-multimeter.md

@@ -1,5 +1,4 @@
-Analog recording with multimeter
-================================
+# Analog recording with multimeter
 
 As of r89xx, NEST replaces a range of analog recording devices, such as
 voltmeter, conductancemeter and aeif\_w\_meter with a universal *multimeter*,
@@ -32,8 +31,7 @@ Multimeter works essentially as the old-style voltmeter, but with a few changes:
 
 -   Any node can only be recorded from by one multimeter.
 
-Adapting scripts using voltmeter
---------------------------------
+## Adapting scripts using voltmeter
 
 Many NEST users have scripts that use voltmeter to record membrane potential.
 To ease the transition to the new-style analog recording, NEST still provides a
@@ -48,8 +46,7 @@ events/V\_m instead of from events/potentials, e.g.
     array([-70.        , -70.        , -70.        , -70.        ,
            -70.        , -70.        , -70.        , -70.        ,
 
-An example
-----------
+## An example
 
 As an example, here is the multimeter.py example from the PyNEST examples set:
 

extras/userdoc/md/documentation/community.md

@@ -1,8 +1,6 @@
-Community
-=========
+# Community
 
-Getting support
----------------
+## Getting support
 
 The NEST User Mailing list is intended to be a forum for questions on the usage
 of NEST, the exchange of code and general discussions about NEST.
@@ -18,8 +16,7 @@ Subscription
 Archive (only subscribed users)  
 <http://mail.nest-initiative.org/cgi-bin/mailman/listinfo/nest_user>
 
-Contributing
-------------
+## Contributing
 
 NEST draws its strength from the many people that use and improve it. We are
 happy to consider your contributions (e.g. own models, bug or documentation
@@ -29,8 +26,7 @@ Please see the [NEST developer space](http://nest.github.io/nest-simulator) for
 information about the development workflow of NEST and for how to create a fork
 of our Git repository and pull requests against it.
 
-Reporting bugs
---------------
+## Reporting bugs
 
 The primary place to go to if you find an error is the [GitHub issue tracker
 for NEST](https://github.com/nest/nest-simulator/issues). Please take the time

extras/userdoc/md/documentation/connection_management.md → extras/userdoc/md/documentation/connection-management.md

@@ -1,21 +1,20 @@
-Connection Management
-=====================
+# Connection Management
 
 From NEST 2.4 onwards the old connection routines (i.e.
 `(Random)ConvergentConnect`, `(Random)DivergentConnect` and plain `Connect`) are
 replaced by one unified `Connect` function. In
-[SLI](an_introduction_to_sli.md "An Introduction to SLI")
+[SLI](an-introduction-to-sli.md)
 ,the old syntax of the function still works, while in
-[PyNEST](introduction-to-pynest.md "PyNEST"), the `Connect()`
+[PyNEST](introduction-to-pynest.md), the `Connect()`
 function has been renamed to `OneToOneConnect()`. However, simple cases, which
 are just creating one-to-one connections between two lists of nodes are still
 working with the new command without the need to change the code. Note that the
 topology-module is not effected by theses changes. The translation between the
-old and the new connect routines is described in [Old Connection Routines](connection_management.md#Old-Connection-Routines).
+old and the new connect routines is described in [Old Connection Routines](connection-management.md#old-connection-routines).
 
 The connectivity pattern is defined inside the `Connect()` function under the
 key 'rule'. The patterns available are described in
-[Connection Rules](connection_management.md#Connection-Rules). In
+[Connection Rules](connection-management.md#connection-rules). In
 addition the synapse model can be specified within the connect function and all
 synaptic parameters can be randomly distributed.
 
@@ -46,19 +45,17 @@ string defining the synapse model (default: 'static\_synapse') or as a
 dictionary. By using the key-word variant (`Connect(pre, post,
 syn_spec=syn_spec_dict)`), the conn\_spec can be omitted in the call to
 connect and 'all\_to\_all' is assumed as the default.
-The exact usage of the synapse dictionary is described in [Synapse Specification](connection_management.md#Synapse-Specification).
+The exact usage of the synapse dictionary is described in [Synapse Specification](connection-management.md#synapse-specification).
 
-Connection Rules
-----------------
+## Connection Rules
 
 Connection rules are specified using the `conn_spec` parameter, which can be a
 string naming a connection rule or a dictionary containing a rule specification.
 Only connection rules requiring no parameters can be given as strings, for all
 other rules, a dictionary specifying the rule and its parameters, such as in-
 or out-degrees, is required.
 
-one-to-one
-----------
+## one-to-one
 
 The i<sup>th</sup> node in `pre` is connected to the i<sup>th</sup> node in
 `post`. The node lists pre and post have to be of the same length.
@@ -84,8 +81,7 @@ Example:
     delay = 0.5
     Connect(A[0], B[0], weight, delay)
 
-all-to-all
-----------
+## all-to-all
 
 ![all-to-all connections](../../img/All_to_all.png)
 all-to-all connections
@@ -162,7 +158,7 @@ Example:
 
 The synapse properties can be given as a string or a dictionary. The string can
 be the name of a pre-defined synapse which can be found in the synapsedict (see
-[Synapse Types](connection_management.md#Synapse-Types)) or a
+[Synapse Types](connection-management.md#synapse-types)) or a
 manually defined synapse via `CopyModel()`.
 
 Example:
@@ -185,7 +181,7 @@ parameter types, as long as they agree with the connection routine ('rule').
 
 **Scalar** parameters must be given as floats except for the 'receptor\_type'
 which has to be initialized as an integer. For more information on the receptor
-type see [Receptor Types](connection_management.md#Synapse-Types) .
+type see [Receptor Types](connection-management.md#synapse-types) .
 
 Example:
 
@@ -304,10 +300,9 @@ needs to be defined in two steps:
     Connect(A, B, syn_spec=syn_dict)
 
 For further information on the distributions see
-[Random numbers in NEST](random_numbers.md "Random numbers in NEST").
+[Random numbers in NEST](random-numbers.md).
 
-Old Connection Routines
------------------------
+## Old Connection Routines
 
 The old connection routines are still available in NEST 2.4, apart from the old
 `Connect()` which has been renamed to `OneToOneConnect()` and whose the support
@@ -442,17 +437,15 @@ Example new connection routine:
     syn_dict = {'model': 'my_synapse', 'weight': w0, 'delay': w0}
     nest.Connect(A, B, conn_dict, syn_dict)
 
-Topological Connections
------------------------
+## Topological Connections
 
 If the connect functions above are not sufficient, the topology provides more
 sophisticated functions. For example, it is possible to create receptive field
 structures and much more! See
-[Topological Connections](Topology_UserManual.pdf)
+[Topological Connections](http://www.nest-simulator.org/wp-content/uploads/2015/04/Topology_UserManual.pdf)
 for more information.
 
-Receptor Types
---------------
+## Receptor Types
 
 Each connection in NEST targets a specific receptor type on the post-synaptic
 node. Receptor types are identified by integer numbers, the default receptor
@@ -491,8 +484,7 @@ The code block above connects a standard integrate-and-fire neuron to a somatic
 excitatory receptor of a multi-compartment integrate-and-fire neuron model. The
 result is illustrated in the figure.
 
-Synapse Types
--------------
+## Synapse Types
 
 NEST supports multiple synapse types that are specified during connection setup.
 The default synapse type in NEST is `static_synapse`. Its weight does not change
@@ -550,8 +542,7 @@ copied model are taken.
 events a synapse type is able to transmit is documented in the *Transmits*
 section of the model documentation.
 
-Inspecting Connections
-----------------------
+## Inspecting Connections
 
 `GetConnections(source=None, target=None, synapse_model=None)`: Return an array
 of identifiers for connections that match the given parameters. source and
@@ -581,8 +572,7 @@ function, which will then return a list with the parameters of the connections:
       'source': 1,
       'receptor': 0}]
 
-Modifying existing Connections
-------------------------------
+## Modifying existing Connections
 
 To modify the connections of an existing connection, one also has to obtain
 handles to the connections with `GetConnections()` first. These can then be

extras/userdoc/md/documentation/continuous_integration.md → extras/userdoc/md/documentation/continuous-integration.md

@@ -1,8 +1,6 @@
-Continuous Integration
-======================
+# Continuous Integration
 
-Introduction
-------------
+## Introduction
 
 [**Continuous Integration**](http://en.wikipedia.org/wiki/Continuous_integration) (CI)
 is a software development practice where quality control is continuously
@@ -29,8 +27,7 @@ getting into the tree and timely reporting of identified problems. This
 way, issues will be discovered earlier and the amount of efforts to fix
 them will be significantly decreased (hopefully).
 
-Continuous Integration at NEST Initiative
---------------------------------------------------------------------------------------------------------------------------
+## Continuous Integration at NEST Initiative
 
 The current CI implementation is now available at the following URL:
 
@@ -115,8 +112,7 @@ to the build system:
 
 -   Yury V. Zaytsev
 
-Further reading
----------------
+## Further reading
 
 -   [Martin Fowler's paper on Continuous
     Integration](http://martinfowler.com/articles/continuousIntegration.html)

extras/userdoc/md/documentation/documentation.md

@@ -1,30 +1,25 @@
-Documentation
-=============
+# Documentation
 
-[Installing NEST](installation.md "Installation")
------------------------------------------------------------------------------
+## [Installing NEST](installation.md)
 
-[Introduction to PyNEST](introduction-to-pynest.md "Introduction to PyNEST")
---------------------------------------------------------------------------------------------------------
+## [Introduction to PyNEST](introduction-to-pynest.md)
 
-NEST User Manual
----------------------------------------------------------------------------
+## NEST User Manual
 
--   [Frequently Asked Questions](frequently_asked_questions.md "Frequently Asked Questions")
--   [Analog recording with multimeter](analog_recording_with_multimeter.md "Analog recording with multimeter")
--   [Connection Management](connection_management.md "Connection Management")
--   [Topological Connections](wp-content/uploads/2015/04/Topology_UserManual.pdf "Topological Connections")
--   [Random numbers in NEST](random_numbers.md "Random numbers in NEST")
--   [Parallel Computing](parallel_computing.md "Parallel Computing")
+-   [Frequently Asked Questions](frequently-asked-questions.md)
+-   [Analog recording with multimeter](analog-recording-with-multimeter.md)
+-   [Connection Management](connection-management.md)
+-   [Topological Connections](http://www.nest-simulator.org/wp-content/uploads/2015/04/Topology_UserManual.pdf)
+-   [Random numbers in NEST](random-numbers.md)
+-   [Parallel Computing](parallel-computing.md)
 -   [Scheduling and simulation flow](scheduling-and-simulation-flow.md)
 -   [Simulations with precise spike times](simulations-with-precise-spike-times.md)
--   [Using NEST with MUSIC](using_nest_with_music.md "Using NEST with MUSIC")
--   [Using NEST with the SLI interpreter](an_introduction_to_sli.md "An Introduction to SLI")
+-   [Using NEST with MUSIC](using-nest-with-music.md)
+-   [Using NEST with the SLI interpreter](an-introduction-to-sli.md)
 -   [NEST/SLI Quick Reference](quickref.md)
 -   [NEST Command Index](helpindex.md)
 
-Example Networks
-----------------
+## Example Networks
 
 -   [brunel_alpha_nest](py_samples/brunel_alpha_nest.md)
 -   [precise_spiking](py_samples/precise_spiking.md)
@@ -62,15 +57,13 @@ Example Networks
 -   [if_curve](py_samples/if_curve.md)
 -   [sinusoidal_gamma_generator](py_samples/sinusoidal_gamma_generator.md)
 
-Further Reading
----------------
+## Further Reading
 
 -   [NEST by Example](wp-content/uploads/2015/02/NEST_by_Example.pdf)
--   Read and improve the [NEST article on  Scholarpedia.org](cholarpedia.org/article/NEST_\(NEural_Simulation_Tool))
--   Read and improve the [NEST article on Wikipedia](http://en.wikipedia.org/wiki/NEST_\(software))
+-   Read and improve the [NEST article on  Scholarpedia.org](http://scholarpedia.org/article/NEST_\(NEural_Simulation_Tool\))
+-   Read and improve the [NEST article on Wikipedia](http://en.wikipedia.org/wiki/NEST_\(software\))
 
-NEST Developer Manual
----------------------
+## NEST Developer Manual
 
 For information about modifying and extending NEST and contributing your code
 to the official version, please head over to the [NEST Developer Space](http://nest.github.io/nest-simulator.html).

extras/userdoc/md/documentation/download.md

@@ -1,19 +1,17 @@
-Download & Releases
-===================
+# Download & Releases
 
-NEST is available under the [GNU General Public License 2 or later](license/index.html "License").
+NEST is available under the [GNU General Public License 2 or later](license.md).
 This means that you can
 
 -   use NEST for your research,
 -   modify and improve NEST according to your needs,
 -   distribute NEST to others under the same license.
 
-To find out more about NEST, see the [list of features](features.md "Features")
-and the [user documentation](documentation.md "Documentation").
-For details about how to contribute to the development of NEST, see the [developer space](http://nest.github.io/nest-simulator "Development").
+To find out more about NEST, see the [list of features](features.md)
+and the [user documentation](documentation.md).
+For details about how to contribute to the development of NEST, see the [developer space](http://nest.github.io/nest-simulator).
 
-Citing NEST
------------
+## Citing NEST
 
 Please cite NEST in any of your work which is based on NEST.
 
@@ -23,7 +21,7 @@ The full citation is available in different formats on
 [Zenodo](http://dx.doi.org/10.5281/zenodo.44222).
 
 For all other versions below NEST v2.8.0 use: Gewaltig M-O & Diesmann M (2007)
-[NEST (Neural Simulation Tool)](http://www.scholarpedia.org/article/NEST_(Neural_Simulation_Tool) "")
+[NEST (Neural Simulation Tool)](http://www.scholarpedia.org/article/NEST_(Neural_Simulation_Tool))
 *Scholarpedia* 2(4):1430.
 
 Here is a suitable BibTeX entry:
@@ -41,8 +39,7 @@ Here is a suitable BibTeX entry:
 If you tell us about your publications that used NEST, we will add it to our
 publication list, thus making it visible to potential readers.
 
-Ubuntu 15.10 Live Media with NEST 2.8.0
----------------------------------------
+## Ubuntu 15.10 Live Media with NEST 2.8.0
 
 **[Download](http://www.nest-simulator.org/downloads/gplreleases/lubuntu-15.10_nest-2.8.0.ova)** (OVA, ~2.3G)          **[Checksum](http://www.nest-simulator.org/downloads/gplreleases/lubuntu-15.10_nest-2.8.0.ova.sha512sum)** (sha512sum)