unified docs: one file for all languages (#3466)

* restructure toward unified docs
* removed n. reference in HOC for ions and elsewhere
* another n. fix
* optimization, compilation options, and main progref link
* C++ snippet in compilationoptions wasn't labeled as such
* removed :hoc:
* unified rxd docs, export no longer requires a special import
Also some minor cleanups to export code
* change all `:hoc:` to :
* rst parsing is now tab-aware
* doc handling fixes: whitespace, functions, tests
* typo fix
* h->n in HOC rxd example

---------

Co-authored-by: Rie Sakai <riemy1689@gmail.com>

Author: ramcdougal

CMakeLists.txt

@@ -952,7 +952,7 @@ if(NRN_ENABLE_PYTHON)
     help_data_dat
     COMMAND ${CMAKE_COMMAND} -E make_directory ${PROJECT_BINARY_DIR}/lib/python/neuron
     COMMAND ${NRN_DEFAULT_PYTHON_EXECUTABLE} ${PROJECT_SOURCE_DIR}/docs/parse_rst.py
-            ${PROJECT_SOURCE_DIR}/docs/python ${PROJECT_BINARY_DIR}/lib/python/neuron/help_data.dat
+            ${PROJECT_SOURCE_DIR}/docs/progref ${PROJECT_BINARY_DIR}/lib/python/neuron/help_data.dat
     COMMENT "Generating help_data.dat"
     VERBATIM)
   add_dependencies(nrniv_lib help_data_dat)

docs/conf.py

@@ -25,7 +25,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "NEURON"
-copyright = "2022, Duke, Yale and the Blue Brain Project"
+copyright = "2025, Duke, Yale and the Blue Brain Project"
 author = "Michael Hines"
 
 # -- General configuration ---------------------------------------------------

docs/courses/artificial_cells_neuron.rst

@@ -16,12 +16,12 @@ NEURON has four built-in point process classes which can be used to construct ar
     `NetStim <https://nrn.readthedocs.io/en/latest/python/modelspec/programmatic/mechanisms/mech.html?highlight=netstim#NetStim>`_ produces a user-specified train of one or more output events, and can also be triggered by input events
 
 2.
-    :hoc:class:`IntFire1`, which acts like a leaky integrator driven by delta function inputs. That is, the state variable m decays exponentially toward 0. 
+    :class:`IntFire1`, which acts like a leaky integrator driven by delta function inputs. That is, the state variable m decays exponentially toward 0. 
     Arrival of an event with weight w causes an abrupt change in m. 
     If m exceeds 1, an output event is generated and the cell enters a refractory period during which it ignores further inputs. At the end of the refractory period, m is reset to 0 and the cell becomes responsive to new inputs.
 
 3.
-    :hoc:class:`IntFire2`, a leaky integrator with time constant taum driven by a total current that is the sum of
+    :class:`IntFire2`, a leaky integrator with time constant taum driven by a total current that is the sum of
 
         { a user-settable constant "bias" current }
 
@@ -31,7 +31,7 @@ NEURON has four built-in point process classes which can be used to construct ar
 
     Net synaptic current decays toward 0 with time constant taus, where taus > taum (synaptic current decays slowly compared to the rate at which "membrane potential" m equilibrates). When an input event with weight w arrives, the net synaptic current changes abruptly by the amount w.
 
-4. :hoc:class:`IntFire4`, with fast excitation current (rises abruptly, decays exponentially) and slower alpha function like inhibition current that is integrated by even slower membrane.
+4. :class:`IntFire4`, with fast excitation current (rises abruptly, decays exponentially) and slower alpha function like inhibition current that is integrated by even slower membrane.
 
 NEURON requires that all point processes be located in a section. To meet this (in this context, conceptually irrelevant) requirement, the Network Builder tool locates each point process of its instantiated artificial cells in the dummy section called ``acell_home_``
 

docs/courses/bulletin_board_walkthrough.rst

@@ -60,9 +60,9 @@ loads the cell's source code
 Instrumentation
 >>>>>>>>>>>>>>>
 
-stimulus--attaches an :hoc:class:`IClamp` to ``soma(0.5)``
+stimulus--attaches an :class:`IClamp` to ``soma(0.5)``
 
-data recording and analysis--uses a :hoc:class:`NetCon` to record the times at which spikes reach ``dend(1)``
+data recording and analysis--uses a :class:`NetCon` to record the times at which spikes reach ``dend(1)``
 
 get_frequency(spvec) verifies that enough spikes have occurred, then calculates freq from the last NINVL=10 recorded ISIs.
 

docs/courses/hoc_exercises.rst

@@ -195,7 +195,7 @@ Must declare an object reference (=object variable) before making an object
 
 Objref: manipulate references to objects, not the objects themselves
 
-- often names are chosen that make it easy to remember what an object reference is to be used for (eg g for a :hoc:class:`Graph` or vec for a :hoc:class:`Vector`) but it's important to remember that these are just for convenience and that any object reference can be used to point to any kind of object
+- often names are chosen that make it easy to remember what an object reference is to be used for (eg g for a :class:`Graph` or vec for a :class:`Vector`) but it's important to remember that these are just for convenience and that any object reference can be used to point to any kind of object
 
 Objects include vectors, graphs, lists, ...
 ###########################################
@@ -261,7 +261,7 @@ Lists are useful for maintaining pointers to objects so that they are maintained
 
 1. Make vec point to a new vector. Print out and record its identity (``print vec``). Now print using the object name (ie print Vector[#] with the right #). This confirms that the object exists. Destroy the object by reinitializing the vec reference. Now try to print using the object name. What does it say.
 
-2. As in Exercise 1: make vec point to a new :hoc:class:`Vector` and use print to find the vector name. Make XO a reference to a new list. Append the vector to the list: {XO.append(vec). Now dereference vec as in Exercise 1. Print out the object by name and confirm that it still exists. Even though the original objref is gone, it is still pointed to by the list.
+2. As in Exercise 1: make vec point to a new :class:`Vector` and use print to find the vector name. Make XO a reference to a new list. Append the vector to the list: {XO.append(vec). Now dereference vec as in Exercise 1. Print out the object by name and confirm that it still exists. Even though the original objref is gone, it is still pointed to by the list.
 
 3. Identify the vector on the list: (``print XO.object(0)``). Remove the vector from the list (``print XO.remove(0)``). Confirm that this vector no longer exists.
 
@@ -423,12 +423,12 @@ Graph
 
 .. seealso:: 
 
-    :hoc:class:`Graph`
+    :class:`Graph`
 
 Exercises
 #########
 
-1. write ``proc`` that draws a colored line ($1) from (0, 0) to given coordinate ($2, $3) assume g is a :hoc:class:`Graph` object
+1. write ``proc`` that draws a colored line ($1) from (0, 0) to given coordinate ($2, $3) assume g is a :class:`Graph` object
 
 2. write a ``proc`` that puts up two new graphs
 
@@ -467,15 +467,15 @@ Vector
 
 .. seealso::
 
-    :hoc:class:`Vector`
+    :class:`Vector`
 
 Exercises
 #########
 
 1. 
     Write a ``proc`` to make ``$o1`` vec elements the product of $o2*$o3 elements
 
-    (Use :hoc:meth:`Vector.resize` to get ``$o1`` to right size; generate error if sizes wrong e.g. ``if ($o2.size!=$o3.size) { print "ERROR: wrong sizes" return }``)
+    (Use :meth:`Vector.resize` to get ``$o1`` to right size; generate error if sizes wrong e.g. ``if ($o2.size!=$o3.size) { print "ERROR: wrong sizes" return }``)
 
 2.
     Graph vector values: ``vec.line(g, 1)`` or ``vec.mark(g, 1)``
@@ -487,7 +487,7 @@ Exercises
 4.
     Write a ``proc`` to multiply the elements of a vector by sequential values from ``1`` to ``size-1``
 
-    Hint: use :hoc:meth:`vec.resize <Vector.resize>`, :hoc:meth:`vec.indgen <Vector.indgen>`, :hoc:meth:`vec.mul <Vector.mul>`
+    Hint: use :meth:`vec.resize <Vector.resize>`, :meth:`vec.indgen <Vector.indgen>`, :meth:`vec.mul <Vector.mul>`
 
 File
 ~~~~
@@ -517,7 +517,7 @@ File
 
 .. seealso::
 
-    :hoc:class:`File`
+    :class:`File`
 
 Exercises
 #########
@@ -554,7 +554,7 @@ List
 
 .. seealso::
 
-    :hoc:class:`List`
+    :class:`List`
 
 Exercises
 #########
@@ -621,7 +621,7 @@ Recording the simulation
 
 .. seealso::
 
-    :hoc:meth:`Vector.record`
+    :meth:`Vector.record`
 
 Graphing and analyzing data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -669,5 +669,5 @@ Roll your own GUI
 Exercise
 ########
 
-1. put up panel to run sim and display (in an :hoc:func:`xvalue`) the average frequency
+1. put up panel to run sim and display (in an :func:`xvalue`) the average frequency
 

docs/courses/hopfield_brody_network_in_python.rst

@@ -9,7 +9,7 @@ Although this is a minimal model, learning the ropes is still difficult. Therefo
 
 As you know, NEURON is optimized to handle the complex channel and compartment simulations that have been omitted from this exercise. The interested student might wish to convert this network into a network of spiking cells with realistic inhibitory interactions or a hybrid network with both realistic and artificial cells. Such an extended exercise would more clearly demonstrate NEURON's advantages for performing network simulations.
 
-Standard intfire implementation (eg :hoc:class:`IntFire1` from ``intfire1.mod``))
+Standard intfire implementation (eg :class:`IntFire1` from ``intfire1.mod``))
 ---------------------
 
 Individual units are integrate-and-fire neurons.

docs/courses/network_ready_cells_from_the_cellb.rst

@@ -163,7 +163,7 @@ Use the "Weights" button to pop up a NetEdgeGUI panel and enter the following we
 Simulation 
 ++++++++++
 
-In the NetGUI window, press the "Create" button. The :hoc:func:`topology()` statement should produce
+In the NetGUI window, press the "Create" button. The :func:`topology()` statement should produce
 
 .. code::
 

docs/guide/faq.rst

@@ -293,12 +293,12 @@ pulsedistrib also contains :download:`data/ipulse3.mod`, :download:`data/ipulse3
 I want a current clamp that will generate a pulse when I send it an event, or that I can use to produce pulses at precalculated times.
 -----------------------
 
-Then get `pulsedistrib.zip <http://www.neuron.yale.edu/neuron/static/docs/repstim/pulsedistrib.zip>`_, and unzip it. Inside the pulsedistrib subdirectory you'll find :download:`data/ipulse3.mod`, :download:`data/ipulse3rig.ses`, and :download:`data/test_3.hoc` (and some other files that pertain to the previous question). :download:`data/ipulse3.mod` contains the NMODL code for a current clamp that produces a current pulse when it receives an input event. :download:`data/test_3.hoc` is a simple demo of the Ipulse3 mechanism, and :download:`data/ipulse3rig.ses` is used by :download:`data/test_3.hoc` to create the GUI for a demo of Ipulse3. It uses a :hoc:class:`NetStim` to generate the events that drive the Ipulse3. If you want to drive an Ipulse3 with recorded or precomputed event times, use the VecStim class as described under the topic `Driving a synapse with recorded or precomputed spike events <https://www.neuron.yale.edu/phpBB/viewtopic.php?f=28&t=2117>`_ in the "Hot tips" area of the `NEURON Forum <https://www.neuron.yale.edu/phpBB/>`_.
+Then get `pulsedistrib.zip <http://www.neuron.yale.edu/neuron/static/docs/repstim/pulsedistrib.zip>`_, and unzip it. Inside the pulsedistrib subdirectory you'll find :download:`data/ipulse3.mod`, :download:`data/ipulse3rig.ses`, and :download:`data/test_3.hoc` (and some other files that pertain to the previous question). :download:`data/ipulse3.mod` contains the NMODL code for a current clamp that produces a current pulse when it receives an input event. :download:`data/test_3.hoc` is a simple demo of the Ipulse3 mechanism, and :download:`data/ipulse3rig.ses` is used by :download:`data/test_3.hoc` to create the GUI for a demo of Ipulse3. It uses a :class:`NetStim` to generate the events that drive the Ipulse3. If you want to drive an Ipulse3 with recorded or precomputed event times, use the VecStim class as described under the topic `Driving a synapse with recorded or precomputed spike events <https://www.neuron.yale.edu/phpBB/viewtopic.php?f=28&t=2117>`_ in the "Hot tips" area of the `NEURON Forum <https://www.neuron.yale.edu/phpBB/>`_.
 
 I have a set of recorded or calculated spike times. How can I use these to drive a postsynaptic mechanism?
 ------------------------
 
-Assuming that your synaptic mechanism has a ``NET_RECEIVE`` block, so that it is driven by events delivered by a :hoc:class:`NetCon`, I can think of two ways this might be done. Which one to use depends on how many calculated spike times you are dealing with.
+Assuming that your synaptic mechanism has a ``NET_RECEIVE`` block, so that it is driven by events delivered by a :class:`NetCon`, I can think of two ways this might be done. Which one to use depends on how many calculated spike times you are dealing with.
 
 If you only have a "few" spikes (up to a few dozen), you could just dump them into the spike queue at the onset of the simulation. Here's how: 
 

docs/guide/hoc_chapter_11_old_reference.rst

@@ -31,7 +31,7 @@ When NEURON is installed, four programs are constructed from the combinations of
 
 **ivoc**
 
-    OC with C++ classes and graphical interface (which is written in C++). This is the best starting place for building non-neural applications. These C++ classes are implemented in :file:`ivoc/SRC`. The files here are of general use apart from the neuron simulation domain and generally implement the graphical interface, eg. :hoc:class:`Graph`, :hoc:func:`xpanel`, :hoc:class:`VBox`, etc. However the :hoc:class:`File`, :hoc:class:`List`, :hoc:class:`Vector`, and :hoc:class:`Random` class are very useful even if no window manager is present.
+    OC with C++ classes and graphical interface (which is written in C++). This is the best starting place for building non-neural applications. These C++ classes are implemented in :file:`ivoc/SRC`. The files here are of general use apart from the neuron simulation domain and generally implement the graphical interface, eg. :class:`Graph`, :func:`xpanel`, :class:`VBox`, etc. However the :class:`File`, :class:`List`, :class:`Vector`, and :class:`Random` class are very useful even if no window manager is present.
 
 **nrniv**
 
@@ -360,7 +360,7 @@ Names introduced by nrnoc
 	VClamp	SVClamp	IClamp	AlphaSynapse
 	APCount
 
-Missing from the above list are the built-in object classes such as :hoc:class:`List`, :hoc:class:`Graph`, :hoc:class:`HBox`, :hoc:class:`File`, :hoc:class:`Deck`, :hoc:class:`Random`, :hoc:class:`Vector` and some new functions such as :hoc:class:`fit\_praxis`, :hoc:class:`xmenu`, :hoc:class:`xbutton`, etc, as well as neuron specific classes such as :hoc:class:`Shape`, :hoc:class:`SectionList`, etc. The help files in :hoc:class:`NEURONHOME/lib/help` are kept up to date but this file tends to lag behind the current version.
+Missing from the above list are the built-in object classes such as :class:`List`, :class:`Graph`, :class:`HBox`, :class:`File`, :class:`Deck`, :class:`Random`, :class:`Vector` and some new functions such as :class:`fit\_praxis`, :class:`xmenu`, :class:`xbutton`, etc, as well as neuron specific classes such as :class:`Shape`, :class:`SectionList`, etc. The help files in :class:`NEURONHOME/lib/help` are kept up to date but this file tends to lag behind the current version.
 
 Variables
 ---------
@@ -612,7 +612,7 @@ As a trivial example of a function definition, consider:
         return $1 * $1 
     } 
 
-This defines the function :hoc:class:`f(arg1)` which returns the square of its argument. User defined functions can be used in any expression.
+This defines the function :class:`f(arg1)` which returns the square of its argument. User defined functions can be used in any expression.
 
 Functions can be called recursively. For example, the factorial function, can be defined as
 

docs/guide/optimization2.rst

@@ -328,7 +328,7 @@ Then we write our own custom ``init()`` procedure that uses a forall loop to giv
 
 To simplify future code maintenance, we probably should put both of these code fragments into a single file called :file:`params.hoc`.
 
-To make use of :file:`params.hoc`, we have to add a new :hoc:func:`load_file` statement to :file:`init_iclampopt.hoc`. The proxy variables have to exist before the MRF can use them, so :file:`params.hoc` must be loaded before :file:`iclampfit.ses`. Here's the new :file:`init_iclampopt.hoc` :
+To make use of :file:`params.hoc`, we have to add a new :func:`load_file` statement to :file:`init_iclampopt.hoc`. The proxy variables have to exist before the MRF can use them, so :file:`params.hoc` must be loaded before :file:`iclampfit.ses`. Here's the new :file:`init_iclampopt.hoc` :
 
 .. code::
   hoc