Merge pull request #4540 from lbl-srg/maint_10.0.x_patch_userGuide_format

Updated userguide format (maint_10.0.x)

Author: mwetter

.github/workflows/formatting.yml

@@ -24,7 +24,7 @@ jobs:
     # Skip if the commit message contains "ci skip"
     if: "!contains(github.event.head_commit.message, 'ci skip')"
 
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
 
     steps:
       # Checks-out repository under $GITHUB_WORKSPACE, so job can access it
@@ -33,11 +33,11 @@ jobs:
 
       - uses: actions/setup-python@v4
         with:
-          python-version: '3.10.11' # Version range or exact version of a Python version to use, using SemVer's version range syntax
+          python-version: '3.12.3' # Version range or exact version of a Python version to use, using SemVer's version range syntax
           architecture: 'x64'      # optional x64 or x86. Defaults to x64 if not specified
 
       - name: "Install pip"
-        run: pip3 install --upgrade pip wheel
+        run: pip3 install --upgrade pip
 
       - name: "Install BuildingsPy"
         run: pip3 install git+https://github.com/lbl-srg/BuildingsPy@v5.1.0

Buildings/Resources/Documentation/userGuide/Makefile

@@ -44,10 +44,10 @@ html:
 regressiontest: clean
 	@echo "Verify whether all files compile and no uncommitted changes exist"
 	@rm -rf virEnv
-	python -m venv virEnv
-	source virEnv/bin/activate
-	pip install -r requirements.txt --no-deps
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	python3 -m venv virEnv
+	source virEnv/bin/activate && \
+	pip install -r requirements.txt --no-deps && \
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html && \
 	rm -rf virEnv
 	git diff --exit-code .
 

Buildings/Resources/Documentation/userGuide/build/html/_sources/bestPractice.rst.txt

@@ -42,9 +42,9 @@ Building large system models
 When creating a large system model, it is typically easier to build the system model
 through the composition of subsystem models that can be tested in isolation. For example,
 the package
-`Buildings.Examples.ChillerPlant.BaseClasses.Controls.Examples <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Examples_ChillerPlant_BaseClasses_Controls_Examples.html#Buildings.Examples.ChillerPlant.BaseClasses.Controls.Examples>`_
+`Buildings.Examples.ChillerPlant.BaseClasses.Controls.Examples <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Examples_ChillerPlant_BaseClasses_Controls_Examples.html#Buildings.Examples.ChillerPlant.BaseClasses.Controls.Examples>`_
 contains small test models that are used to test individual components in the large system model
-`Buildings.Examples.ChillerPlant <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Examples_ChillerPlant.html#Buildings.Examples.ChillerPlant>`_.
+`Buildings.Examples.ChillerPlant <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Examples_ChillerPlant.html#Buildings.Examples.ChillerPlant>`_.
 Creating small test models typically saves time as the proper response of controls, and the proper operation of subsystems, can be tested in isolation of complex system-interactions that are often present in large models.
 
 
@@ -111,8 +111,8 @@ We will now explain how state variables, such as temperature and pressure, can b
 
 Consider a model consisting of a mass flow source ``Modelica.Fluid.Sources.MassFlowSource_T``, a fluid volume ``Buildings.Fluid.MixingVolumes.MixingVolume`` and
 a fixed boundary condition ``Buildings.Fluid.Sources.Boundary_pT``,
-connected in series as shown in the figure below. Note that the instance ``bou``
-implements an equation that sets the medium pressure at its port, i.e., the port pressure ``bou.ports.p`` is fixed.
+connected in series as shown in the figure below. Note that the instance ``sin``
+implements an equation that sets the medium pressure at its port, i.e., the port pressure ``sin.ports.p`` is fixed.
 
 .. figure:: img/MixingVolumeInitialization.*
    :width: 300px
@@ -270,9 +270,9 @@ a fluid port represents the physical phenomena that was intended to model.
 
 However, in more complex flow configurations, one may want to explicitly control what branches of a piping or duct network mix.
 This may be achieved by using an instance of the model
-`Junction <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.Junction>`_
+`Junction <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.Junction>`_
 as shown in the left figure below, which is derived from the test model
-`BoilerPolynomialClosedLoop <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_Boilers_Examples.html#Buildings.Fluid.Boilers.Examples.BoilerPolynomialClosedLoop>`_
+`BoilerPolynomialClosedLoop <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_Boilers_Examples.html#Buildings.Fluid.Boilers.Examples.BoilerPolynomialClosedLoop>`_
 
 .. _fig_flu_cor_wro:
 
@@ -283,7 +283,7 @@ as shown in the left figure below, which is derived from the test model
 
 In :numref:`fig_flu_cor_wro` (a), the mixing points have been correctly defined by
 use of the model
-`Junction <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.Junction>`_.
+`Junction <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.Junction>`_.
 However, in :numref:`fig_flu_cor_wro` (b), all connections are made to the port of the instance ``spl2``.
 This results in the same configuration as is shown in :numref:`fig_flu_cor_wro` (c).
 This is certainly not the intention of the modeler, as this causes all flows to be mixed in the port.
@@ -301,13 +301,13 @@ Use of sensors in fluid flow systems
 When selecting a sensor model, a distinction needs to be made whether the measured quantity depends on
 the direction of the flow or not. If the quantity depends on the flow direction,
 such as temperature or relative humidity, then sensors with two ports from the
-`Buildings.Fluid.Sensors <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_Sensors.html#Buildings.Fluid.Sensors>`_
+`Buildings.Fluid.Sensors <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_Sensors.html#Buildings.Fluid.Sensors>`_
 library should be used. These sensors have a more efficient implementation than sensors with
 one port for situations where the flow reverses its direction.
 The proper use sensors is described in the
-`User's Guide <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_Sensors_UsersGuide.html>`_
+`User's Guide <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_Sensors_UsersGuide.html>`_
 of the
-`Buildings.Fluid.Sensors <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_Sensors.html#Buildings.Fluid.Sensors>`_
+`Buildings.Fluid.Sensors <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_Sensors.html#Buildings.Fluid.Sensors>`_
 package.
 
 
@@ -319,9 +319,9 @@ Reference pressure for incompressible fluids such as water
 This section explains how to set a reference pressure for fluids that model
 the flow as :term:`incompressible flow`,
 such as
-`Buildings.Media.Water <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Media_Water.html#Buildings.Media.Water>`_
+`Buildings.Media.Water <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Media_Water.html#Buildings.Media.Water>`_
 and
-`Buildings.Media.Antifreeze.PropyleneGlycolWater <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Media_Antifreeze_PropyleneGlycolWater.html#Buildings.Media.Antifreeze.PropyleneGlycolWater>`_.
+`Buildings.Media.Antifreeze.PropyleneGlycolWater <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Media_Antifreeze_PropyleneGlycolWater.html#Buildings.Media.Antifreeze.PropyleneGlycolWater>`_.
 
 Consider the flow circuit shown in :numref:`fig_flow_cir` that consists of a pump or fan,
 a flow resistance and a volume.
@@ -354,7 +354,7 @@ In this situation, attempting to translate the model leads, in Dymola, to the fo
    The number of scalar Real equation elements are 58.
 
 Similarly, if the medium model
-`Buildings.Media.Specialized.Water.TemperatureDependentDensity <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Media_Specialized_Water_TemperatureDependentDensity.html#Buildings.Media.Specialized.Water.TemperatureDependentDensity>`_,
+`Buildings.Media.Specialized.Water.TemperatureDependentDensity <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Media_Specialized_Water_TemperatureDependentDensity.html#Buildings.Media.Specialized.Water.TemperatureDependentDensity>`_,
 which models density as a function of pressure and enthalpy, is used, then
 the model is well-defined, but the pressure increases the longer the pump runs.
 The reason is that the pump adds heat to the water. When the water temperature
@@ -364,7 +364,7 @@ the pressure increases from :math:`1 \, \mathrm{bars}` to :math:`150 \, \mathrm{
 To avoid this singularity or increase in pressure,
 use a model that imposes a pressure source and that accounts for the expansion of the fluid.
 For example, use
-`Buildings.Fluid.Sources.Boundary_pT <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_Sources.html#Buildings.Fluid.Sources.Boundary_pT>`_
+`Buildings.Fluid.Sources.Boundary_pT <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_Sources.html#Buildings.Fluid.Sources.Boundary_pT>`_
 to form the system model shown in :numref:`fig_flow_cir_wit_bou`.
 
 .. _fig_flow_cir_wit_bou:
@@ -376,15 +376,15 @@ to form the system model shown in :numref:`fig_flow_cir_wit_bou`.
    provides a reference presssure.
 
 Alternatively, you may use
-`Buildings.Fluid.Storage.ExpansionVessel <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_Storage.html#Buildings.Fluid.Storage.ExpansionVessel>`_,
+`Buildings.Fluid.Storage.ExpansionVessel <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_Storage.html#Buildings.Fluid.Storage.ExpansionVessel>`_,
 but
-`Buildings.Fluid.Sources.Boundary_pT <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_Sources.html#Buildings.Fluid.Sources.Boundary_pT>`_
+`Buildings.Fluid.Sources.Boundary_pT <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_Sources.html#Buildings.Fluid.Sources.Boundary_pT>`_
 usually leads to simpler equations than
-`Buildings.Fluid.Storage.ExpansionVessel <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_Storage.html#Buildings.Fluid.Storage.ExpansionVessel>`_.
+`Buildings.Fluid.Storage.ExpansionVessel <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_Storage.html#Buildings.Fluid.Storage.ExpansionVessel>`_.
 Note that the medium that flows out of the fluid port of
-`Buildings.Fluid.Sources.Boundary_pT <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_Sources.html#Buildings.Fluid.Sources.Boundary_pT>`_
+`Buildings.Fluid.Sources.Boundary_pT <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_Sources.html#Buildings.Fluid.Sources.Boundary_pT>`_
 is at a fixed temperature, while the model
-`Buildings.Fluid.Storage.ExpansionVessel <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_Storage.html#Buildings.Fluid.Storage.ExpansionVessel>`_
+`Buildings.Fluid.Storage.ExpansionVessel <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_Storage.html#Buildings.Fluid.Storage.ExpansionVessel>`_
 conserves energy.
 However, since the thermal expansion of the fluid is usually small,
 this effect can be neglected in most building HVAC applications.
@@ -393,10 +393,10 @@ this effect can be neglected in most building HVAC applications.
 
    In each water circuit, there must be exactly on instance of
    `Buildings.Fluid.Sources.Boundary_pT
-   <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_Sources.html#Buildings.Fluid.Sources.Boundary_pT>`_,
+   <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_Sources.html#Buildings.Fluid.Sources.Boundary_pT>`_,
    or instance of
    `Buildings.Fluid.Storage.ExpansionVessel
-   <https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_Storage.html#Buildings.Fluid.Storage.ExpansionVessel>`_.
+   <https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_Storage.html#Buildings.Fluid.Storage.ExpansionVessel>`_.
 
    If there is more than one such device, then there are multiple
    points in the system that set the reference static pressure.
@@ -592,5 +592,5 @@ is produced. This shows the iteration variables and their start values.
 These start values can be overwritten in the model.
 
 
-.. _PressureDrop: https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.PressureDrop
-.. _WetCoilDiscretized: https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_HeatExchangers.html#Buildings.Fluid.HeatExchangers.WetCoilDiscretized
+.. _PressureDrop: https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.PressureDrop
+.. _WetCoilDiscretized: https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Fluid_HeatExchangers.html#Buildings.Fluid.HeatExchangers.WetCoilDiscretized