docs: link brainpy.state relationship and fix stale doc URLs

brainpy/state/README.md

@@ -6,6 +6,8 @@ The `brainpy.state` module provides a state-based programming interface for brai
 
 State-based programming offers an alternative paradigm for defining and managing neural models, emphasizing explicit state management and transformations for building complex brain dynamics systems.
 
+`brainpy.state` is the recommended starting point for new `State`-based, differentiable models; the classic `DynamicalSystem`-based `brainpy` API (`brainpy.dyn`, `brainpy.math`, `brainpy.integrators`) is unchanged and fully supported. The two paradigms coexist — see the [relationship declaration](https://brainx.chaobrain.com/brainpy-state/project/relationship.html) for how they relate.
+
 ## Features
 
 - **Explicit State Management**: Clear separation between model state and computation logic
@@ -17,7 +19,7 @@ State-based programming offers an alternative paradigm for defining and managing
 
 For comprehensive documentation on state-based programming in BrainPy, please visit:
 
-- **State-based Documentation**: https://brainpy-state.readthedocs.io/
+- **State-based Documentation**: https://brainx.chaobrain.com/brainpy-state/
 - **Main BrainPy Documentation**: https://brainpy.readthedocs.io/
 
 ## Source Repository

docs/api.rst

@@ -20,7 +20,17 @@ API Documentation
    apis/optim.rst
    apis/running.rst
    apis/mixin.rst
-   ``brainpy.state`` module <https://brainpy-state.readthedocs.io/api/index.html>
+   ``brainpy.state`` module <https://brainx.chaobrain.com/brainpy-state/apis/index.html>
+
+.. admonition:: ``brainpy`` and ``brainpy.state``
+
+   ``brainpy.state`` is the state-based modeling layer of BrainPy — developed and
+   released as the standalone ``brainpy_state`` package and surfaced here through the
+   ``brainpy.state`` namespace (bundled with ``brainpy >= 2.7.6``; no separate install
+   needed). It is the recommended starting point for new ``State``-based, differentiable
+   spiking-network models, while the classic ``DynamicalSystem``-based API is unchanged
+   and fully supported. See the `brainpy.state relationship page
+   <https://brainx.chaobrain.com/brainpy-state/project/relationship.html>`_.
 
 The following APIs will no longer be maintained in the future, but you can still use them normally.
 

docs/index.rst

@@ -118,7 +118,7 @@ Learn more
 
       .. card:: :material-regular:`data_exploration;2em` ``brainpy.state`` APIs
          :class-card: sd-text-black sd-bg-light
-         :link: https://brainpy-state.readthedocs.io/
+         :link: https://brainx.chaobrain.com/brainpy-state/
 
 
 ----