Merge pull request #3427 from jessica-mitchell/fix-sphinx

jessica-mitchell · web-flow · commit 64bf40e882bc · 2025-03-20T14:46:45.000+01:00
Fix sphinx warnings in docs
diff --git a/doc/htmldoc/_ext/list_examples.py b/doc/htmldoc/_ext/list_examples.py
@@ -28,8 +28,8 @@
 from sphinx.application import Sphinx
 from sphinx.util.docutils import SphinxDirective
 
-logging.basicConfig(level=logging.WARNING)
 log = logging.getLogger(__name__)
+log.setLevel(level=logging.WARNING)
 
 
 class listnode(nodes.General, nodes.Element):
diff --git a/doc/htmldoc/_ext/model_tag_setup.py b/doc/htmldoc/_ext/model_tag_setup.py
@@ -27,9 +27,8 @@
 from pathlib import Path
 from pprint import pformat
 
-logging.basicConfig(level=logging.INFO)
 log = logging.getLogger(__name__)
-
+log.setLevel(level=logging.WARNING)
 # The following function is used in two other functions, in two separate Sphinx events
 
 
diff --git a/doc/htmldoc/community.rst b/doc/htmldoc/community.rst
@@ -64,7 +64,7 @@ Contact us
 Get help
 --------
 
-.. grid:: 
+.. grid::
 
    .. grid-item-card:: Command line help
       :link: command_help
@@ -102,7 +102,7 @@ Explore the NEST ecosystem
        :link: https://nest-simulator.org
        :link-type: url
 
-   .. grid-item-card:: Become a NEST initiative member 
+   .. grid-item-card:: Become a NEST initiative member
          :link: https://www.nest-initiative.org/
          :link-type: url
 
@@ -113,6 +113,4 @@ Explore the NEST ecosystem
   :hidden:
 
   related_projects
-  citing-nest
   getting_help
-
diff --git a/doc/htmldoc/conf.py b/doc/htmldoc/conf.py
@@ -214,6 +214,7 @@
     "extmod": ("https://nest-extension-module.readthedocs.io/en/latest/", None),
 }
 
+suppress_warnings = ["config.cache"]
 
 nitpick_ignore = [
     ("py:class", "None"),
diff --git a/doc/htmldoc/developer_space/index.rst b/doc/htmldoc/developer_space/index.rst
@@ -6,9 +6,9 @@ Developer space
 Here is all documentation pertaining to the development of NEST.
 It is documentation for anyone needing to touch the code or documentation.
 
-.. grid:: 3 
+.. grid:: 3
 
-  .. grid-item-card:: 
+  .. grid-item-card::
        :link-type: ref
        :link: dev_install
        :class-card: sd-bg-success sd-text-white
@@ -112,11 +112,11 @@ Developer guides
 
 .. toctree::
    :maxdepth: 1
-   :hidden: 
+   :hidden:
    :glob:
 
    workflows/*
-   workflows/documentation_workflow/*
+   workflows/documentation_workflow/index
    guidelines/*
    guidelines/styleguide/styleguide
    guidelines/styleguide/vim_support_sli
diff --git a/doc/htmldoc/examples/index.rst b/doc/htmldoc/examples/index.rst
@@ -313,8 +313,6 @@ PyNEST examples
    ../auto_examples/urbanczik_synapse_example
    ../auto_examples/iaf_tum_2000_short_term_depression
    ../auto_examples/iaf_tum_2000_short_term_facilitation
-   ../auto_examples/compartmental_model/receptors_and_current
-   ../auto_examples/compartmental_model/two_comps
    ../auto_examples/lin_rate_ipn_network
    ../auto_examples/rate_neuron_dm
    ../auto_examples/brunel_alpha_nest
@@ -323,20 +321,6 @@ PyNEST examples
    ../auto_examples/brunel_exp_multisynapse_nest
    ../auto_examples/brunel_alpha_evolution_strategies
    ../auto_examples/sonata_example/index
-   ../auto_examples/sonata_example/sonata_network
-   ../auto_examples/spatial/conncomp
-   ../auto_examples/spatial/conncon_sources
-   ../auto_examples/spatial/conncon_targets
-   ../auto_examples/spatial/connex
-   ../auto_examples/spatial/connex_ew
-   ../auto_examples/spatial/ctx_2n
-   ../auto_examples/spatial/gaussex
-   ../auto_examples/spatial/grid_iaf
-   ../auto_examples/spatial/grid_iaf_irr
-   ../auto_examples/spatial/grid_iaf_oc
-   ../auto_examples/spatial/test_3d
-   ../auto_examples/spatial/test_3d_exp
-   ../auto_examples/spatial/test_3d_gauss
    ../auto_examples/testiaf
    ../auto_examples/repeated_stimulation
    ../auto_examples/multimeter_file
@@ -354,24 +338,6 @@ PyNEST examples
    ../auto_examples/csa_spatial_example
    ../auto_examples/hpc_benchmark
    ../auto_examples/astrocytes/index
-   ../auto_examples/astrocytes/astrocyte_single
-   ../auto_examples/astrocytes/astrocyte_interaction
-   ../auto_examples/astrocytes/astrocyte_small_network
-   ../auto_examples/astrocytes/astrocyte_brunel
    ../auto_examples/EI_clustered_network/index
    ../auto_examples/eprop_plasticity/index
    ../auto_examples/wang_decision_making
-
-.. toctree::
-   :hidden:
-
-   ../auto_examples/sudoku/sudoku_net
-   ../auto_examples/sudoku/sudoku_solver
-   ../auto_examples/sudoku/plot_progress
-
-.. toctree::
-   :hidden:
-
-   ../auto_examples/pong/run_simulations
-   ../auto_examples/pong/pong
-   ../auto_examples/pong/generate_gif
diff --git a/doc/htmldoc/get-started_index.rst b/doc/htmldoc/get-started_index.rst
@@ -221,13 +221,8 @@ More topics
    Devices  <devices/index>
    Spatially-structured networks <networks/spatially_structured_networks>
    High performance computing <hpc/index>
-   NEST models <models/index>
    NEST and SONATA <nest_sonata/nest_sonata_guide>
-   Simulation behavior <nest_behavior/running_simulations>
-   Randomness in NEST <nest_behavior/random_numbers>
-   Built-in timers <nest_behavior/built-in_timers>
    Connect NEST with other tools <interface_nest/index>
-   From NEST 2.x to 3.x <whats_new/v3.0/refguide_nest2_nest3>
 
 .. toctree::
    :hidden:
diff --git a/doc/htmldoc/hpc/optimizing_nest.rst b/doc/htmldoc/hpc/optimizing_nest.rst
@@ -3,14 +3,6 @@
 Optimize performance of HPC Systems
 ===================================
 
-.. toctree::
-  :hidden:
-
-  overview_hardware
-  slurm_script
-  threading
-  mpi_processes
-
 
 If you are new to running NEST on HPC systems or trying to improve the performance or debug issues,
 we have provided a few guides to help you out. There are a few things to consider about the
diff --git a/doc/htmldoc/installation/developer.rst b/doc/htmldoc/installation/developer.rst
@@ -33,7 +33,7 @@ file that contains all possible packages needed for NEST development.
 
    .. grid-item-card:: Install NEST with mamba
 
-         See our instructions for installing NEST from source in a :ref:`mamba environment <mambenva>`
+         See our instructions for installing NEST from source in a :ref:`mamba environment <condaenv>`
 
    .. grid-item-card:: Install NEST without environment
 
diff --git a/doc/htmldoc/nest_behavior/built-in_timers.rst b/doc/htmldoc/nest_behavior/built-in_timers.rst
@@ -16,20 +16,20 @@ querying the corresponding kernel attributes. For example:
 
 The following basic time measurements are available:
 
-+-----------------------------+----------------------------------+
-|Name                         |Explanation                       |
-+=============================+==================================+
-|``time_construction_create`` |Cumulative time NEST spent        |
-|			                  |creating	neurons and devices      |
-+-----------------------------+----------------------------------+
-|``time_construction_connect``|Cumulative time NEST spent        |
-|                             |creating connections              |
-+-----------------------------+----------------------------------+
-|``time_simulate``            |Time NEST spent in the last       |
-|                             |``Simulate()``                    |
-+-----------------------------+----------------------------------+
-
-.. note ::
++-------------------------------+----------------------------------+
+| Name                          | Explanation                      |
++===============================+==================================+
+| ``time_construction_create``  | Cumulative time NEST spent       |
+|                               | creating neurons and devices     |
++-------------------------------+----------------------------------+
+| ``time_construction_connect`` | Cumulative time NEST spent       |
+|                               | creating connections             |
++-------------------------------+----------------------------------+
+| ``time_simulate``             | Time NEST spent in the last      |
+|                               | ``Simulate()``                   |
++-------------------------------+----------------------------------+
+
+.. note::
 
    While preparing the actual simulation after network construction, NEST needs to build the pre-synaptic part of the
    connection infrastructure, which requires MPI communication (`Jordan et al. 2018
@@ -40,18 +40,18 @@ The following basic time measurements are available:
 
 In the context of NEST performance monitoring, other useful kernel attributes are:
 
-+-----------------------+----------------------------------+
-|Name                   |Explanation                       |
-+=======================+==================================+
-|``biological_time``    |Cumulative simulated time         |
-+-----------------------+----------------------------------+
-|``local_spike_counter``|Number of spikes emitted by the   |
-|                       |neurons represented on this MPI   |
-|			            |rank during the last              |
-|                       |``Simulate()``                    |
-+-----------------------+----------------------------------+
++-------------------------+-----------------------------------+
+| Name                    | Explanation                       |
++=========================+===================================+
+| ``biological_time``     | Cumulative simulated time         |
++-------------------------+-----------------------------------+
+| ``local_spike_counter`` | Number of spikes emitted by the   |
+|                         | neurons represented on this MPI   |
+|                         | rank during the last              |
+|                         | ``Simulate()``                    |
++-------------------------+-----------------------------------+
 
-.. note ::
+.. note::
 
    ``nest.ResetKernel()`` resets all time measurements as well as ``biological_time`` and ``local_spike_counter``.
 
@@ -65,40 +65,43 @@ simulation cycle, but they can impact the runtime. Therefore, detailed timers ar
 
 If detailed timers are active, the following time measurements are available as kernel attributes:
 
-+--------------------------------+----------------------------------+----------------------------------+
-|Name                            |Explanation                       |Part of                           |
-+================================+==================================+==================================+
-|``time_gather_target_data``     |Cumulative time for communicating |``time_communicate_prepare``      |
-|                                |connection information from       |                                  |
-|				                 |postsynaptic to presynaptic side  |                                  |
-+--------------------------------+----------------------------------+----------------------------------+
-|``time_communicate_target_data``|Cumulative time for core MPI      |``time_gather_target_data``       |
-|                                |communication when gathering      |                                  |
-|			                	 |target data                       |                                  |
-+--------------------------------+----------------------------------+----------------------------------+
-|``time_update``                 |Time for neuron update            |``time_simulate``                 |
-+--------------------------------+----------------------------------+----------------------------------+
-|``time_gather_spike_data``      |Time for complete spike exchange  |``time_simulate``                 |
-|                                |after update phase                |                                  |
-+--------------------------------+----------------------------------+----------------------------------+
-|``time_collocate_spike_data``   |Time to collocate MPI send buffer |``time_gather_spike_data``        |
-|                                |from spike register               |                                  |
-+--------------------------------+----------------------------------+----------------------------------+
-|``time_communicate_spike_data`` |Time for communicating spikes     |``time_gather_spike_data``        |
-|                                |between compute nodes             |                                  |
-+--------------------------------+----------------------------------+----------------------------------+
-|``time_deliver_spike_data``     |Time to deliver events from the   |``time_gather_spike_data``        |
-|                                |MPI receive buffers to their      |                                  |
-|                                |local synaptic targets (including |                                  |
-|                                |synaptic update, e.g. STDP        |                                  |
-|                                |synapses) and to the spike ring   |                                  |
-|                                |buffers of the corresponding      |                                  |
-|                                |postsynaptic neurons              |                                  |
-+--------------------------------+----------------------------------+----------------------------------+
-|``time_omp_synchronization_construction`` |Synchronization time of threads during network construction. |``time_construction_create``, ``time_construction_connect``, ``time_communicate_prepare``        |
-+--------------------------------+----------------------------------+----------------------------------+
-|``time_omp_synchronization_simulation`` |Synchronization time of threads during simulation. |``time_simulate``        |
-+--------------------------------+----------------------------------+----------------------------------+
++-------------------------------------------+-----------------------------------+----------------------------------+
+| Name                                      | Explanation                       | Part of                          |
++===========================================+===================================+==================================+
+| ``time_gather_target_data``               | Cumulative time for communicating | ``time_communicate_prepare``     |
+|                                           | connection information from       |                                  |
+|                                           | postsynaptic to presynaptic side  |                                  |
++-------------------------------------------+-----------------------------------+----------------------------------+
+| ``time_communicate_target_data``          | Cumulative time for core MPI      | ``time_gather_target_data``      |
+|                                           | communication when gathering      |                                  |
+|                                           | target data                       |                                  |
++-------------------------------------------+-----------------------------------+----------------------------------+
+| ``time_update``                           | Time for neuron update            | ``time_simulate``                |
++-------------------------------------------+-----------------------------------+----------------------------------+
+| ``time_gather_spike_data``                | Time for complete spike exchange  | ``time_simulate``                |
+|                                           | after update phase                |                                  |
++-------------------------------------------+-----------------------------------+----------------------------------+
+| ``time_collocate_spike_data``             | Time to collocate MPI send buffer | ``time_gather_spike_data``       |
+|                                           | from spike register               |                                  |
++-------------------------------------------+-----------------------------------+----------------------------------+
+| ``time_communicate_spike_data``           | Time for communicating spikes     | ``time_gather_spike_data``       |
+|                                           | between compute nodes             |                                  |
++-------------------------------------------+-----------------------------------+----------------------------------+
+| ``time_deliver_spike_data``               | Time to deliver events from the   | ``time_gather_spike_data``       |
+|                                           | MPI receive buffers to their      |                                  |
+|                                           | local synaptic targets (including |                                  |
+|                                           | synaptic update, e.g. STDP        |                                  |
+|                                           | synapses) and to the spike ring   |                                  |
+|                                           | buffers of the corresponding      |                                  |
+|                                           | postsynaptic neurons              |                                  |
++-------------------------------------------+-----------------------------------+----------------------------------+
+| ``time_omp_synchronization_construction`` | Synchronization time of threads   | ``time_construction_create``,    |
+|                                           | during network construction.      | ``time_construction_connect``,   |
+|                                           |                                   | ``time_communicate_prepare``     |
++-------------------------------------------+-----------------------------------+----------------------------------+
+| ``time_omp_synchronization_simulation``   | Synchronization time of threads   | ``time_simulate``                |
+|                                           | during simulation.                |                                  |
++-------------------------------------------+-----------------------------------+----------------------------------+
 
 MPI synchronization timer
 -------------------------
@@ -107,11 +110,11 @@ via the ``-Dwith-mpi-sync-timer=ON`` CMake flag. This timer measures the time be
 (i.e., neuron state propagation) and start of collective communication of spikes between all MPI processes. This timer
 adds an additional MPI barrier right before the start of communication, which might affect performance.
 
-+-----------------------------+---------------------------------------+
-|Name                         |Explanation                            |
-+=============================+=======================================+
-|``time_mpi_synchronization`` |Time spent waiting for other processes.|
-+-----------------------------+---------------------------------------+
++------------------------------+-----------------------------------------+
+| Name                         | Explanation                             |
++==============================+=========================================+
+| ``time_mpi_synchronization`` | Time spent waiting for other processes. |
++------------------------------+-----------------------------------------+
 
 Multi-threaded timers
 ---------------------
diff --git a/doc/htmldoc/related_projects.rst b/doc/htmldoc/related_projects.rst
@@ -98,7 +98,7 @@ real-time operation.
 TheVirtualBrain (TVB)
 ---------------------
 
-:ref:`TVB <tvb:index>` is a framework for the simulation of the dynamics of large-scale brain networks with
+:doc:`TVB <tvb:index>` is a framework for the simulation of the dynamics of large-scale brain networks with
 biologically realistic connectivity.
 
 * :ref:`Get started with TVB <tvb:tutorial_0_GettingStarted>`
diff --git a/doc/htmldoc/whats_new/index.rst b/doc/htmldoc/whats_new/index.rst
@@ -31,4 +31,4 @@ the new versions.
    v3.3/*
    v3.2/*
    v3.1/*
-   v3.0/*
+   v3.0/index
diff --git a/doc/htmldoc/whats_new/v3.0/features/index.rst b/doc/htmldoc/whats_new/v3.0/features/index.rst
@@ -21,10 +21,6 @@ Here you can discover the new features NEST 3.0 has to offer!
    :maxdepth: 1
    :hidden:
 
-   ../../../neurons/node_handles
-   ../../../synapses/handling_connections
-   ../../../neurons/parametrization
    random_number_generators
    recording_simulations
    stimulation_backends
-   ../../../interface_nest/nest_server
diff --git a/doc/htmldoc/whats_new/v3.7/index.rst b/doc/htmldoc/whats_new/v3.7/index.rst
@@ -55,7 +55,7 @@ populations.
 See examples using astrocyte models:
 
 * :doc:`../../../auto_examples/astrocytes/astrocyte_small_network`
-* :doc:`../../../auto_examples/astrocytes/astrocyte_brunel`
+* :doc:`../../../auto_examples/astrocytes/astrocyte_brunel_bernoulli`
 
 See connectivity documentation:
 
diff --git a/pynest/examples/astrocytes/astrocyte_small_network.py b/pynest/examples/astrocytes/astrocyte_small_network.py
@@ -131,7 +131,8 @@
 See Also
 ~~~~~~~~
 
-:doc:`astrocyte_brunel`
+:doc:`astrocyte_brunel_bernoulli`
+
 
 """
 
diff --git a/pynest/examples/eprop_plasticity/eprop_supervised_regression_handwriting_bsshslm_2020.py b/pynest/examples/eprop_plasticity/eprop_supervised_regression_handwriting_bsshslm_2020.py
@@ -593,7 +593,7 @@ def get_weights(pop_pre, pop_post):
 
 # %% ###########################################################################################################
 # Plot learning performance
-# ...................
+# .........................
 # We begin with a plot visualizing the learning performance of the network: the loss plotted against the
 # iterations.
 
diff --git a/pynest/examples/eprop_plasticity/eprop_supervised_regression_lemniscate_bsshslm_2020.py b/pynest/examples/eprop_plasticity/eprop_supervised_regression_lemniscate_bsshslm_2020.py
diff --git a/pynest/nest/lib/hl_api_connections.py b/pynest/nest/lib/hl_api_connections.py

Original file line number	Diff line number	Diff line change
`@@ -214,6 +214,7 @@`
`214`	`214`	`"extmod": ("https://nest-extension-module.readthedocs.io/en/latest/", None),`
`215`	`215`	`}`
`216`	`216`
	`217`	`+suppress_warnings = ["config.cache"]`
`217`	`218`
`218`	`219`	`nitpick_ignore = [`
`219`	`220`	`("py:class", "None"),`