doc: (fixes #927) Update Python installation instructions

RELEASE_NOTES.md

@@ -27,7 +27,7 @@ requirements (Note: not all ns-3 features are available on all systems):
 - (macOS only) Xcode 11 or later
 - (Windows only) Msys2/MinGW64 toolchain or WSL2
 
-Python API requires [Cppyy](https://cppyy.readthedocs.io/en/latest/installation.html).
+Python API requires [Cppyy](https://cppyy.readthedocs.io/en/latest/installation.html).  Specifically, avoid Cppyy version 3; stay with version 2.4.2 for this release.
 
 ### New user-visible features
 

doc/installation/source/linux.rst

@@ -106,9 +106,11 @@ Please see below subsections for Python-related package requirements.
 Python bindings
 ===============
 
+Python requires `Cppyy, <https://cppyy.readthedocs.io/en/latest/installation.html>` and specifically, version 2.4.2 is the latest version known to work with ns-3 at this time.
+
 ns-3.37 and newer::
 
-  python3 -m pip install --user cppyy
+  python3 -m pip install --user cppyy==2.4.2
 
 ns-3.30-3.36 (also requires pybindgen, found in the ``allinone`` directory)::
 

doc/installation/source/overview.rst

@@ -51,11 +51,9 @@ choose to use a subset of the available libraries; only the ``core`` library is
 |ns3| uses the CMake build system (until release 3.36, the Waf build system was used).  It can be
 built from command-line or via a code editor program.
 
-Most users write C++ ns-3 programs; Python support is less frequently used and is not officially
-maintained as of this writing.  As of *ns-3.37*, |ns3| uses `cppyy` to generate runtime Python
-bindings.  Officially, Python3 support is only lightly maintained, and the `cppyy` support was
-contributed by Gabriel Ferreira as a proof-of-concept (hint: the project is seeking a full-time
-maintainer to develop this further).
+Most users write C++ ns-3 programs; Python support is less frequently used.
+As of *ns-3.37*, |ns3| uses `cppyy` to generate runtime Python
+bindings, and |ns3| is available in the Pip repositories as of ns-3.39 release.
 
 Many users may be familiar with how software is packaged and installed on Linux and other systems
 using package managers.  For example, to install a given Linux development library such as

doc/installation/source/system.rst

@@ -140,7 +140,8 @@ if you are running LTE or NR simulations (which make use of SQLite databases):
 Python bindings (ns-3.37 and newer)
 ===================================
 
-|ns3| Python support now uses `cppyy <https://cppyy.readthedocs.io/en/latest/>`_.
+|ns3| Python support now uses `cppyy <https://cppyy.readthedocs.io/en/latest/>`_.  Version 2.4.2
+is the most recent supported cppyy release; version 3.0.0 is not currently supported.
 
 Using Python bindings (release 3.30 to ns-3.36)
 ===============================================

doc/manual/source/python.rst

@@ -115,10 +115,11 @@ simple modules in python, jump to the `Using the pip wheel`_ section.
 Using the bindings from the ns-3 source
 =======================================
 
-The main prerequisite is to install `cppyy`.  Depending on how you may manage
+The main prerequisite is to install `cppyy`, with version no later than 2.4.2.
+Depending on how you may manage
 Python extensions, the installation instructions may vary, but you can first
 check if it installed by seeing if the `cppyy` module can be
-successfully imported:
+successfully imported and the version is no later than 2.4.2:
 
 .. sourcecode:: bash
 
@@ -127,6 +128,8 @@ successfully imported:
   [GCC 9.4.0] on linux
   Type "help", "copyright", "credits" or "license" for more information.
   >>> import cppyy
+  >>> print("%s" % cppyy.__version)
+  2.4.2
   >>>
 
 If not, you may try to install via `pip` or whatever other manager you are
@@ -134,7 +137,7 @@ using; e.g.:
 
 .. sourcecode:: bash
 
-  $ python3 -m pip install --user cppyy
+  $ python3 -m pip install --user cppyy==2.4.2
 
 First, we need to enable the build of Python bindings:
 
@@ -149,13 +152,13 @@ To run example programs, there are two ways to use ns3 to take care of this.  On
 .. sourcecode:: bash
 
   $ ./ns3 shell
-  $ python3 examples/wireless/mixed-wireless.py
+  $ python3 examples/wireless/mixed-wired-wireless.py
 
 and the other is to use the 'run' option to ns3:
 
 .. sourcecode:: bash
 
-  $ ./ns3 run examples/wireless/mixed-wireless.py
+  $ ./ns3 run examples/wireless/mixed-wired-wireless.py
 
 Use the ``--no-build`` option to run the program without invoking a project rebuild.
 This option may be useful to improve execution time when running the same program
@@ -163,14 +166,14 @@ repeatedly but with different arguments, such as from scripts.
 
 .. sourcecode:: bash
 
-  $ ./ns3 run --no-build examples/wireless/mixed-wireless.py
+  $ ./ns3 run --no-build examples/wireless/mixed-wired-wireless.py
 
 To run a python script under the C debugger:
 
 .. sourcecode:: bash
 
   $ ./ns3 shell
-  $ gdb --args python3 examples/wireless/mixed-wireless.py
+  $ gdb --args python3 examples/wireless/mixed-wired-wireless.py
 
 To run your own Python script that calls |ns3| and that has this path, ``/path/to/your/example/my-script.py``, do the following: