cyclus · abachma2 · Jun 18, 2025 · May 30, 2025 · May 30, 2025 · May 30, 2025
diff --git a/source/arche/cli.rst b/source/arche/cli.rst
@@ -13,7 +13,7 @@ single-string form ``spec`` (e.g. ``:cycamore:Source``) which is discussed
 To view the auto-generated XML schema used for validating archetype
 configuration parameters in input files:
 
-  .. code-block:: bash
+  .. code-block:: console
 
       $ cyclus --agent-schema :agents:Source
       <interleave>
@@ -33,7 +33,7 @@ configuration parameters in input files:
 To view a JSON structured output of all the data generated and collected from
 ``#pragma cyclus`` annotations for a particular archetype:
 
-  .. code-block:: bash
+  .. code-block:: console
 
       $ cyclus --agent-annotations :cycamore:Source
       {
@@ -52,7 +52,7 @@ To view a JSON structured output of all the data generated and collected from
 
 And to list all archetypes inside a particular library:
 
-  .. code-block:: bash
+  .. code-block:: console
 
       $ cyclus --agent-listing :cycamore
       :cycamore:DeployInst
@@ -71,7 +71,7 @@ Archetype Versioning
 The ``cyclus::Agent`` class exposes a ``version()`` member function which can be
 queried with the |Cyclus| CLI. For example,
 
-.. code-block:: bash
+.. code-block:: console
 
     $ cyclus --agent-version :agents:Source
     1.3.1-7-g9a2c9c9
@@ -94,7 +94,7 @@ your own version tag information for some archetype like
 
 and then access the version with
 
-.. code-block:: bash
+.. code-block:: console
 
     $ cyclus --agent-version my/path:my_library:MyArchetype
     My Version
diff --git a/source/arche/cmake.rst b/source/arche/cmake.rst
@@ -3,13 +3,11 @@
 Building Modules with CMake
 ===========================
 
-If you haven't follow the initial example in :ref:`hello_world_cpp`, you should get
-the `Cycstub repo <https://github.com/cyclus/cycstub>`_ by either `cloning the
-repository <https://github.com/cyclus/cycstub.git>`_ or by `downloading the zip
-file <https://github.com/cyclus/cycstub/archive/develop.zip>`_ (see
-:ref:`hello_world_cpp` for further instructions).
+If you haven't followed the initial example in :ref:`hello_world_cpp`, you should use
+``cycstub`` to generate a directory with the "stubs" to build a new archetype.
+(see :ref:`hello_world_cpp` for further instructions).
 
-The Cycstub repo provides a number of critical tools for building your own
+The ``cycstub`` utility provides a number of critical tools for building your own
 module:
 
 * ``install.py``: a basic installation script
@@ -69,7 +67,7 @@ The ``UseCyclus.cmake`` macro suite uses the following terms:
   ``$CYCLUS_INSTALL_PREFIX/lib/cyclus/my_module_dir/``. The value of
   ``$CYCLUS_INSTALL_PREFIX`` can be queried by
 
-  .. code-block:: bash
+  .. code-block:: console
 
       $ cyclus --install-path
 
@@ -97,12 +95,44 @@ listing:
 
 Examples
 --------
-
+
+Module Installation
++++++++++++++++++++
+
+The "Hello World" example only allows you to add multiple archetypes to the same
+module/library, using the `USE_CYCLUS` and `INSTALL_CYCLUS_MODULE` macros.  If
+you call `cycstub` multiple times in the same folder, it requires you to specify
+the same path and library name for each new archetype.  This approach reduces
+the number of libraries and executables that are added to a system, perhaps
+unnecessarily.
+
+The resulting `src/CMakeLists.txt` file will includes lines like this:
+
+.. literalinclude:: module-cmake
+
+This will generate:
+
+* a single shared object library in ``$CYCLUS_INSTALL_PREFIX/lib/cyclus/tutorial``
+  named ``libTutorialLibrary.so`` (\*nix) or ``libTutorialLibrary.dylib`` (mac)
+
+* a single unit test executable in ``$CYCLUS_INSTALL_PREFIX/bin`` named
+  ``TutorialLibrary_unit_tests``
+
+where both incorporate the ``TutorialFacility``, ``TutorialInstitution``, and
+``TutorialRegion`` :term:`archetypes <archetype>`.
+
+
 Standalone Installation
 +++++++++++++++++++++++
 
-Through the :ref:`hello_world` example, three standalone modules are installed
-using a ``src/CMakeLists.txt`` file that looks something like
+There may be cases where one prefers to have separate libraries and executables
+for each archetype.  This is not currently supported by `cycstub` in a direct
+way. However, you can modify the above module approach by editing
+``src/CMakeLists.txt`` and replacing:
+
+.. literalinclude:: module-cmake
+
+with 
 
 .. literalinclude:: standalone-cmake
 
@@ -123,29 +153,5 @@ and three unit test executables in ``$CYCLUS_INSTALL_PREFIX/bin``:
 
 * ``TutorialRegion_unit_tests``
 
-Module Installation
-+++++++++++++++++++
-
-A valid criticism of the hello world standalone approach is that a lot of
-libraries and executables are generated for three modules that are grouped
-together. We can do better!
-
-What if we wanted to install one module named ``helloworld``? Specifically, we
-would want:
-
-* a single shared object library in ``$CYCLUS_INSTALL_PREFIX/lib/cyclus/tutorial``
-  named ``libhelloworld.so`` (\*nix) or ``libhelloworld.dylib`` (mac)
-
-* a single unit test executable in ``$CYCLUS_INSTALL_PREFIX/bin`` named
-  ``helloworld_unit_tests``
-
-where both incorporate the ``TutorialFacility``, ``TutorialInstitution``, and
-``TutorialRegion`` :term:`archetypes <archetype>`.
-
-Such behavior is pretty simple to achieve. We first must call ``UseCyclus`` on
-each of our source file roots to inform the build system of their presence and
-follow up with a call to ``INSTALL_CYCLUS_MODULE``:
-
-.. literalinclude:: module-cmake
 
 
diff --git a/source/arche/errors.rst b/source/arche/errors.rst
@@ -132,7 +132,7 @@ suppress all warnings and a very large number will print them all.  For
 example, if the user wished to print the first 42 warnings of each kind they
 would call |cyclus| as follows:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ cyclus --warn-limit 42 ...
 
@@ -142,7 +142,7 @@ and throws the error.  This is useful for ensuring that only stable code is
 executed or to help uncover what is causing a warning to be thrown.  It takes
 no arguments:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ cyclus --warn-as-error ...
 
diff --git a/source/arche/hello_world_cpp.rst b/source/arche/hello_world_cpp.rst
@@ -4,48 +4,37 @@ Hello, Cyclus! [C++]
 ====================
 This pages walks you through a very simple hello world example using
 |cyclus| agents.  First make sure that you have the dependencies installed,
-namely |Cyclus|, CMake, and a recent version of Python (2.7 or 3.3+).
+namely |Cyclus|, CMake, and a recent version of Python (3.3+).
 
-First, you need to get the ``cycstub`` code.  Cycstub is a skeleton code base
+First, you need to use ``cycstub`` to generate a skeleton code base
 that you can use to quick-start new |cyclus| module development projects.
-You can grab cycstub either by using git to
-`clone the repository <https://github.com/cyclus/cycstub.git>`_ or by
-`downloading the zip file <https://github.com/cyclus/cycstub/archive/develop.zip>`_.
-Let's put this code in a ``tutorial`` directory and go into it.
+``cycstub`` is installed with the main ``cyclus`` kernel and should be
+available wherever ``cyclus`` is available.
 
-**Getting cycstub via git:**
+To use ``cycstub`` to generate the skeleton for a new Facility archetype named ``TutorialFacility`` in
+a module named ``TutorialLibrary`` you can issue the following command:
 
-.. code-block:: bash
+.. code-block:: console
 
-    $ git clone https://github.com/cyclus/cycstub.git tutorial
-    $ cd tutorial
+    $ cycstub --type facility tutorial:TutorialLibrary:TutorialFacility
 
-**Getting cycstub via zip:**
+This will populate the ``tutorial`` directory with a number of files and subdirectories
+that should already be complete for building a new archetype.  Without any changes, this archetype
+will not do anything, but will be a valid archetype for use in a simulation.
 
-.. code-block:: bash
+You can add additional agents to this module by calling `cycstub` multiple times:
 
-    $ curl -L https://api.github.com/repos/cyclus/cycstub/zipball > tutorial.zip
-    $ unzip tutorial.zip
-    $ mv cyclus-cycstub-* tutorial
-    $ cd tutorial
+.. code-block:: console
 
-------------
-
-Since cycstub is a template project everything is named ``stub``. We need to
-change this to reflect the name we want our new project to be called -
-``tutorial`` here.  Cycstub comes with a renaming tool to do just this! From
-the command line, run Python in the following way:
-
-.. code-block:: bash
-
-    tutorial $ python rename.py tutorial
+    $ cycstub --type inst tutorial:TutorialLibrary:TutorialInstitution
+    $ cycstub --type region tutorial:TutorialLibrary:TutorialRegion
 
 ------------
 
 Let's now change the behavior of the TutorialFacility's ``Tick()`` &
 ``Tock()`` member functions to print "Hello" and "World" respectively.  To do
 this, please open up the :file:`src/tutorial_facility.cc` file in your
-favorite text editor (vim, emacs, gedit, `notepad++ <http://exofrills.org>`_).
+favorite text editor (e.g., vim, emacs, gedit, `VS Code <https://code.visualstudio.com/>`_).
 Change the original functions to look like:
 
 **Original Tick() and Tock() in src/tutorial_facility.cc:**
@@ -71,19 +60,19 @@ install the ``tutorial`` project.  This done with the install.py script.
 The install script puts the project into your cyclus userspace,
 ``${HOME}/.local/lib/cyclus``.
 
-.. code-block:: bash
+.. code-block:: console
 
-    tutorial $ python install.py
+    $ python3 install.py
 
 ------------
 
 Let's run |cyclus| with the TutorialFacility! In the input directory there is
-an :file:`example.xml`. Running |cyclus| on this file with the command
-``cyclus input/example.xml`` should produce the following output.
+an :file:`example_tutorial_facility.xml`. Running |cyclus| on this file with the command
+``cyclus example_tutorial_facility.xml`` should produce the following output.
 
-.. code-block:: bash
+.. code-block:: console
 
-    tutorial $ cyclus input/example.xml
+    $ cyclus example_tutorial_facility.xml
                   :
               .CL:CC CC             _Q     _Q  _Q_Q    _Q    _Q              _Q
             CC;CCCCCCCC:C;         /_\)   /_\)/_/\\)  /_\)  /_\)            /_\)

diff --git a/source/arche/hello_world_py.rst b/source/arche/hello_world_py.rst
@@ -71,9 +71,9 @@ an :file:`example.xml`. First modify it to point to the archetype we just wrote.
 Running |cyclus| on this file with the command
 ``cyclus input/example.xml`` should produce the following output.
 
-.. code-block:: bash
+.. code-block:: console
 
-    tutorial $ cyclus input/example.xml
+    $ cyclus input/example.xml
                   :
               .CL:CC CC             _Q     _Q  _Q_Q    _Q    _Q              _Q
             CC;CCCCCCCC:C;         /_\)   /_\)/_/\\)  /_\)  /_\)            /_\)

diff --git a/source/arche/logger.rst b/source/arche/logger.rst
@@ -3,7 +3,7 @@
 Logging
 =======================
 
-.. code-block:: bash
+.. code-block:: console
 
   LOG(LogLevel level, std::string prefix)
 

diff --git a/source/arche/module-cmake b/source/arche/module-cmake
@@ -1,4 +1,4 @@
-USE_CYCLUS("helloworld" "tutorial_facility")
-USE_CYCLUS("helloworld" "tutorial_inst")
-USE_CYCLUS("helloworld" "tutorial_region")
-INSTALL_CYCLUS_MODULE("helloworld" "tutorial")
+USE_CYCLUS("TutorialLibrary" "tutorial_facility")
+USE_CYCLUS("TutorialLibrary" "tutorial_inst")
+USE_CYCLUS("TutorialLibrary" "tutorial_region")
+INSTALL_CYCLUS_MODULE("TutorialLibrary" "")
diff --git a/source/arche/standalone-cmake b/source/arche/standalone-cmake
@@ -1,3 +1,3 @@
-INSTALL_CYCLUS_STANDALONE("TutorialFacility" "tutorial_facility" "tutorial")
-INSTALL_CYCLUS_STANDALONE("TutorialInst" "tutorial_inst" "tutorial")
-INSTALL_CYCLUS_STANDALONE("TutorialRegion" "tutorial_region" "tutorial")
+INSTALL_CYCLUS_STANDALONE("TutorialFacility" "tutorial_facility" "" )
+INSTALL_CYCLUS_STANDALONE("TutorialInstitution" "tutorial_inst" "")
+INSTALL_CYCLUS_STANDALONE("TutorialRegion" "tutorial_region" "")
diff --git a/source/arche/testing.rst b/source/arche/testing.rst
@@ -174,7 +174,7 @@ haven't already, now is a good time to add the ``$CYCLUS_INSTALL_PATH`` to your
 ``~/.local``). Next, from your top level directory (where your ``install.py``
 file is), run: 
 
-.. code-block:: bash
+.. code-block:: console
 
   $ ./install.py
   $ TickTracker_unit_tests
@@ -322,7 +322,7 @@ This will prevent exceptions from being caught resulting in a core-dump.  You
 can then use a debugger (e.g. gdb or lldb) to run the failing simulation and
 investigate the source of the crash in more detail.  Something like this:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ CYCLUS_NO_CATCH=1 gdb --args cyclus my-failing-sim.xml
 
@@ -339,7 +339,7 @@ with respect to resource exchange.  To turn on this debugging, simply run
 cyclus with the environment variable ``CYCLUS_DEBUG_DRE`` set to any non-empty
 value:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ CYCLUS_DEBUG_DRE=1 cyclus my-sim.xml
 

diff --git a/source/arche/tour_cpp.rst b/source/arche/tour_cpp.rst
@@ -2,15 +2,17 @@ A Tour of Cycstub
 =================
 
 Since |Cyclus| version 1.3.1 the Cycstub CLI is included in a standard |Cyclus| installation.
-If you have an older version of |Cyclus| please refer to the `Cycstub repository <https://github.com/cyclus/cycstub>`_
-for installation instructions.
+
 This section will walk through the source files of the stub :term:`archetypes
-<archetype>` in Cycstub. Cycstub provides
-three stub archetypes:
+<archetype>` generated when a user invokes the ``cycstub`` utility.  ``Cycstub``
+can generate stubs for each of the agent types.  The standard usage to generate the 
+stubs for a Facility, Institution or Region, respectively, is:
+
+.. code-block:: console
 
-* ``StubFacility``
-* ``StubInstitution``
-* ``StubRegion``
+  cycstub --type facility :stublibrary:StubFacility
+  cycstub --type institution :stublibrary:StubInstitution
+  cycstub --type region :stublibrary:StubRegion
 
 We will walk through ``StubFacility``\ 's source specifically because its the
 most complicated of the three. 
@@ -34,26 +36,32 @@ which includes most :term:`cyclus kernel` headers as a convenience for new
 include the specific kernel headers you need if you require a smaller
 executable.
 
-Moving on in the header file we come to the class declaration
+Moving on in the header file we come to the class declaration inside the namespace
+of this specific module library, `stublibrary`, with standard Doxygen documentation
+strings.
 
 .. code-block:: cpp
 
+  namespace stublibrary {
+
+  /// @class StubFacility
+  /// ...
+
   class StubFacility : public cyclus::Facility  {
 
 which simply states that the ``StubFacility`` inherits from ``cyclus::Facility``.
 
-We then come to the constructor declaration
+We then come to the constructor declaration in the header file
 
 .. code-block:: cpp
 
   explicit StubFacility(cyclus::Context* ctx);
 
-and implementation
+and definition in the implementation file
 
 .. code-block:: cpp
 
-  StubFacility::StubFacility(cyclus::Context* ctx)
-      : cyclus::Facility(ctx) {};
+  StubFacility::StubFacility(cyclus::Context* ctx) : cyclus::Facility(ctx) {};
 
 The constructor takes a single ``cyclus::Context`` argument. The :term:`context`
 is the mechanism by which :term:`agents <agent>` can query and otherwise

diff --git a/source/arche/tutorial_cpp/setup.rst b/source/arche/tutorial_cpp/setup.rst
@@ -40,9 +40,9 @@ Then make the new archetype, updating all the files as needed
 Finally, open -``src/CMakeLists.txt`` with your favorite text editor and add the
 following line to the end of it
 
-.. code-block:: bash
+.. code-block:: console
 
-    install_cyclus_standalone("Storage" "storage" "tutorial")
+    $ install_cyclus_standalone("Storage" "storage" "tutorial")
 
 
 Install and Test