Changed documentation files according some conventions #371

Merged
merged 33 commits into from Jun 21, 2016

Conversation

Projects
None yet
3 participants
@steffengraber
Contributor

steffengraber commented May 30, 2016

Changed the documentation files according these conventions:

+- [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](http://www.nest-simulator.org/wp-content/uploads/2015/04/Topology_UserManual.pdf "Topological Connections")

This comment has been minimized.

@jougs

jougs May 30, 2016

Contributor

@heplesser: shouldn't we convert the topology manual to an IPython notebook or a plain markdown document at one point? I think the days of PDFs for documentation are over ;-) Can you please note this somewhere?

@jougs

jougs May 30, 2016

Contributor

@heplesser: shouldn't we convert the topology manual to an IPython notebook or a plain markdown document at one point? I think the days of PDFs for documentation are over ;-) Can you please note this somewhere?

This comment has been minimized.

@heplesser

heplesser May 31, 2016

Contributor

@jougs Good idea! I created #374 to remind me about it.

@heplesser

heplesser May 31, 2016

Contributor

@jougs Good idea! I created #374 to remind me about it.

@@ -57,19 +50,17 @@ Accuracy
- By default spikes are restricted to the grid spanned by the computation time
step
-- For some neuron models [spike interaction in continuous time](simulations-with-precise-spike-times/)
+- For some neuron models [spike interaction in continuous time](simulations-with-precise-spike-times-md "spike interaction in continuous time")

This comment has been minimized.

@jougs

jougs May 30, 2016

Contributor

.md instead of -md

@jougs

jougs May 30, 2016

Contributor

.md instead of -md

extras/userdoc/md/documentation/index.md
@@ -153,17 +148,15 @@ we will add it to our [publication list](publications.md "Publications"),
thus making it visible to potential readers. Send us your reference or even a
reprint, using the mail address given on the [contact page](impressum.md "Impressum").
-NEST logo for your poster or presentation
------------------------------------------
+## NEST logo for your poster or presentation
If you like NEST, why not show it on your poster or on your slides?
<https://github.com/nest/nest-simulator/tree/master/extras/logos>
![](../../../logos/nest-simulated.png)

This comment has been minimized.

@jougs

jougs May 30, 2016

Contributor

This image is too large on the current homepage. Can we make it smaller, please?

@jougs

jougs May 30, 2016

Contributor

This image is too large on the current homepage. Can we make it smaller, please?

This comment has been minimized.

@steffengraber

steffengraber May 31, 2016

Contributor

Changed on the homepage.

@steffengraber

steffengraber May 31, 2016

Contributor

Changed on the homepage.

This comment has been minimized.

@jougs

jougs May 31, 2016

Contributor

Thanks! Is it also possible to set an appropriate size here in markdown?

@jougs

jougs May 31, 2016

Contributor

Thanks! Is it also possible to set an appropriate size here in markdown?

-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 "First Steps")

This comment has been minimized.

@jougs

jougs May 30, 2016

Contributor

I would remove the title part of the link, e.g. make this link just

[First Steps](first-steps.md)

According to https://silktide.com/i-thought-title-text-improved-accessibility-i-was-wrong/, the title part is less useful than one (including me) would naively think.

If we decide to do remove this part, it should be done for all occurrences.

@jougs

jougs May 30, 2016

Contributor

I would remove the title part of the link, e.g. make this link just

[First Steps](first-steps.md)

According to https://silktide.com/i-thought-title-text-improved-accessibility-i-was-wrong/, the title part is less useful than one (including me) would naively think.

If we decide to do remove this part, it should be done for all occurrences.

This comment has been minimized.

@steffengraber

steffengraber May 31, 2016

Contributor

Interesting.
But, if we see it as a sort of extra info to the link in markdown (to do what ever with it) we can leave it optional.
And, if we decide to remove it, how can we insert some more link info?
What do you think?

@steffengraber

steffengraber May 31, 2016

Contributor

Interesting.
But, if we see it as a sort of extra info to the link in markdown (to do what ever with it) we can leave it optional.
And, if we decide to remove it, how can we insert some more link info?
What do you think?

This comment has been minimized.

@jougs

jougs May 31, 2016

Contributor

Currently, the title is the same as the link text for most links. Therefore, I think that we don't actually need it. We can always re-add it later if we have a use for it. Thus I vote for removing it everywhere.

@jougs

jougs May 31, 2016

Contributor

Currently, the title is the same as the link text for most links. Therefore, I think that we don't actually need it. We can always re-add it later if we have a use for it. Thus I vote for removing it everywhere.

This comment has been minimized.

@steffengraber

steffengraber May 31, 2016

Contributor

ok.

@jougs

This comment has been minimized.

Show comment
Hide comment
@jougs

jougs May 30, 2016

Contributor

Many thanks for this. Can you please check why it does not apply cleanly and look at my comments?

Contributor

jougs commented May 30, 2016

Many thanks for this. Can you please check why it does not apply cleanly and look at my comments?

@jougs

This comment has been minimized.

Show comment
Hide comment
@jougs

jougs May 30, 2016

Contributor

One more thing: can you please add a README.md to the md directory that explains the conventions and what the directory contains? Thanks!

Contributor

jougs commented May 30, 2016

One more thing: can you please add a README.md to the md directory that explains the conventions and what the directory contains? Thanks!

After NEST is installed and configured properly, you can start to build your
model.
### Examples
A good starting point to learn more about modeling in NEST are the
-[example networks](more-example-networks.md "Example networks")
-that come together with NEST.
+example networks that come together with NEST.

This comment has been minimized.

@jougs

jougs May 31, 2016

Contributor

Why is this link gone now?

@jougs

jougs May 31, 2016

Contributor

Why is this link gone now?

This comment has been minimized.

@steffengraber

steffengraber Jun 1, 2016

Contributor

Sorry it is NOT working right now.

@steffengraber

steffengraber Jun 1, 2016

Contributor

Sorry it is NOT working right now.

+Please be advised that NEST should currently only be run in a homogeneous MPI
+environment. Running in a heterogenenous environment can lead to unexpected
+results or even crashes.
+Please contact the [NEST community](http://www.nest-simulator.org/community/) if

This comment has been minimized.

@jougs

jougs May 31, 2016

Contributor

Shouldn't this link be

[NEST community](community.md)
@jougs

jougs May 31, 2016

Contributor

Shouldn't this link be

[NEST community](community.md)

This comment has been minimized.

@steffengraber

steffengraber Jun 1, 2016

Contributor

Sorry, an old relict.

@steffengraber

steffengraber Jun 1, 2016

Contributor

Sorry, an old relict.

@@ -231,8 +224,7 @@ is often helpful to call the function `ResetNetwork()` within each loop
iteration. It resets all nodes to their default configuration and wipes the data
from recording devices.
-Command overview\[sec:Command-overview\]
---------------------------------------
+## Command overview\[sec:Command-overview\]

This comment has been minimized.

@jougs

jougs May 31, 2016

Contributor

Do we need the [sec:Command-overview] here? I thought, anchors are created automatically.

@jougs

jougs May 31, 2016

Contributor

Do we need the [sec:Command-overview] here? I thought, anchors are created automatically.

A minimal example for the exchange of spikes between two independent instances
of NEST is given in the example `examples/nest/music/minimalmusicsetup.music`.
-It uses one [SLI script](../an_introduction_to_sli/index.html "An Introduction
+It uses one [SLI script](an-introduction-to-sli.md "An Introduction

This comment has been minimized.

@jougs

jougs May 31, 2016

Contributor

This one still has a title.

@jougs

jougs May 31, 2016

Contributor

This one still has a title.

This comment has been minimized.

@steffengraber

steffengraber Jun 1, 2016

Contributor

Sorry, could not be found by my regular expression, because there was a linebreak.

@steffengraber

steffengraber Jun 1, 2016

Contributor

Sorry, could not be found by my regular expression, because there was a linebreak.

@@ -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)

This comment has been minimized.

@jougs

jougs May 31, 2016

Contributor

Does this link work? Then the one to this file in extras/userdoc/md/documentation/documentation.md should also be shortened like this.

@jougs

jougs May 31, 2016

Contributor

Does this link work? Then the one to this file in extras/userdoc/md/documentation/documentation.md should also be shortened like this.

This comment has been minimized.

@steffengraber

steffengraber Jun 1, 2016

Contributor

No it does not. I changed it.
I need to find the right place for the pdf and other linked files.

@steffengraber

steffengraber Jun 1, 2016

Contributor

No it does not. I changed it.
I need to find the right place for the pdf and other linked files.

@heplesser

This comment has been minimized.

Show comment
Hide comment
@heplesser

heplesser Jun 10, 2016

Contributor

@steffengraber Could you pull the newest changes from master, so that Travis can properly check the one modified code file?

Contributor

heplesser commented Jun 10, 2016

@steffengraber Could you pull the newest changes from master, so that Travis can properly check the one modified code file?

@steffengraber

This comment has been minimized.

Show comment
Hide comment
Contributor

steffengraber commented Jun 10, 2016

@heplesser
Done.

@@ -192,7 +184,7 @@ the help pages. The browser is set as an option of `helpdesk`. Please see the
file `~/.nestrc` for an example setting `firefox` as browser. Please note that
the command `helpdesk` does not work if you have compiled NEST with MPI support,
but you have to enter the address of the helpdesk
-(`file://$PREFIX/share/doc/nest/index.html`) manually into the browser.
+(`file://$PREFIX/share/doc/nest.md`) manually into the browser.

This comment has been minimized.

@jougs

jougs Jun 20, 2016

Contributor

I think this should stay. The browser won't understand markdown.

@jougs

jougs Jun 20, 2016

Contributor

I think this should stay. The browser won't understand markdown.

This comment has been minimized.

@steffengraber

steffengraber Jun 21, 2016

Contributor

Ah, ok, you're absolutely correct.

@steffengraber

steffengraber Jun 21, 2016

Contributor

Ah, ok, you're absolutely correct.

@@ -294,8 +287,7 @@ the neuronal population itself. In the case of loops, check first whether you
can avoid it entirely by passing the entire population into the function - you
usually can.
-Command overview\[sec:Command-overview\]
---------------------------------------
+## Command overview\[sec:Command-overview\]

This comment has been minimized.

@jougs

jougs Jun 20, 2016

Contributor

I think the \[...\] part gan go away, as the anchor is automatically generated

@jougs

jougs Jun 20, 2016

Contributor

I think the \[...\] part gan go away, as the anchor is automatically generated

This comment has been minimized.

@steffengraber

steffengraber Jun 21, 2016

Contributor

ok

@@ -36,15 +34,14 @@ uniformly distributed integers in {0, 1, ..., N}. Random *deviate* generators,
on the other hand, provide random numbers drawn from a range of distributions,
such as the normal or binomial distributions. In most cases, you will be using
random deviate generators. They are in particular used to initialize properties
-during network construction, as described in the sections [Changes in NEST 2.4](../random_numbers/index.html#Changes-in-random-number-generation-in-NEST-2.4) and [Examples](../random_numbers/index.html#Examples) below.
+during network construction, as described in the sections [Changes in NEST 2.4](random-numbers.md#changes-in-random-number-generation-in-NEST-2.4) and [Examples](random-numbers.md#examples) below.

This comment has been minimized.

@jougs

jougs Jun 20, 2016

Contributor

Does the anchor really contain an upper-case NEST?

@jougs

jougs Jun 20, 2016

Contributor

Does the anchor really contain an upper-case NEST?

This comment has been minimized.

@steffengraber

steffengraber Jun 21, 2016

Contributor

No, you're right.

@steffengraber

steffengraber Jun 21, 2016

Contributor

No, you're right.

@jougs

This comment has been minimized.

Show comment
Hide comment
@jougs

jougs Jun 20, 2016

Contributor

👍 once my comments are addressed. Many thanks for the nice work!

Contributor

jougs commented Jun 20, 2016

👍 once my comments are addressed. Many thanks for the nice work!

@steffengraber

This comment has been minimized.

Show comment
Hide comment
@steffengraber

steffengraber Jun 21, 2016

Contributor

Done.

Contributor

steffengraber commented Jun 21, 2016

Done.

@jougs

This comment has been minimized.

Show comment
Hide comment
@jougs

jougs Jun 21, 2016

Contributor

Very nice. I'm merging without second review, as these changes concern only documentation. Many thanks for this contribution!

Contributor

jougs commented Jun 21, 2016

Very nice. I'm merging without second review, as these changes concern only documentation. Many thanks for this contribution!

@jougs jougs merged commit becdfc2 into nest:master Jun 21, 2016

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@steffengraber steffengraber deleted the steffengraber:doc-filename-convention branch Nov 29, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment