Auto: Updates to docs website via CI [skip ci]

docs/api/CSF.Screenplay.IGetsScreenplay.html

@@ -89,7 +89,7 @@ <h5 class="offcanvas-title" id="tocOffcanvasLabel">Table of Contents</h5>
 
 
   <h1 id="CSF_Screenplay_IGetsScreenplay" data-uid="CSF.Screenplay.IGetsScreenplay" class="text-break">
-Interface IGetsScreenplay  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay/IGetsScreenplay.cs/#L18"><i class="bi bi-code-slash"></i></a>
+Interface IGetsScreenplay  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay/IGetsScreenplay.cs/#L23"><i class="bi bi-code-slash"></i></a>
   </h1>
 
   <div class="facts text-secondary">
@@ -123,8 +123,13 @@ <h2 id="CSF_Screenplay_IGetsScreenplay_remarks">Remarks</h2>
 interface with a class of their own, in order to configure and get the <a class="xref" href="CSF.Screenplay.Screenplay.html">Screenplay</a> instance.
 </p>
 <p>
-Note that implementations of this type should have a public parameterless constructor, because they will not
-be resolved from dependency injection.
+Types which implement this interface need only implement the <a class="xref" href="CSF.Screenplay.IGetsScreenplay.html#CSF_Screenplay_IGetsScreenplay_GetScreenplay">GetScreenplay()</a> method, which should build
+and return a Screenplay instance. In almost all cases, developers are advised to use <a class="xref" href="CSF.Screenplay.ScreenplayBuilder.html">ScreenplayBuilder</a>
+to build and return the Screenplay.
+</p>
+<p>
+Note that implementations of this type must have a public parameterless constructor, because they will be instantiated
+via <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.activator.createinstance#system-activator-createinstance(system-type)">CreateInstance(Type)</a> and not resolved from dependency injection.
 </p>
 </div>
 
@@ -137,7 +142,7 @@ <h2 class="section" id="methods">Methods
 
   <h3 id="CSF_Screenplay_IGetsScreenplay_GetScreenplay" data-uid="CSF.Screenplay.IGetsScreenplay.GetScreenplay">
   GetScreenplay()
-  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay/IGetsScreenplay.cs/#L24"><i class="bi bi-code-slash"></i></a>
+  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay/IGetsScreenplay.cs/#L39"><i class="bi bi-code-slash"></i></a>
   </h3>
 
   <div class="markdown level1 summary"><p>Gets the configured Screenplay instance provided by the current type.</p>
@@ -162,6 +167,16 @@ <h4 class="section">Returns</h4>
 
 
 
+  <h4 class="section" id="CSF_Screenplay_IGetsScreenplay_GetScreenplay_remarks">Remarks</h4>
+  <div class="markdown level1 remarks"><p>
+Implementors should create and return a new <a class="xref" href="CSF.Screenplay.Screenplay.html">Screenplay</a> instance from this method; they are strongly urged
+to consider the use of <a class="xref" href="CSF.Screenplay.ScreenplayBuilder.html">ScreenplayBuilder</a> for this purpose.
+As well as the creation of the Screenplay instance itself, they should also add to the service collection any
+services which relate to <a class="xref" href="../glossary/Ability.html">abilities which could be used in the Screenplay</a>.
+It is recommended to use <a class="xref" href="CSF.Screenplay.ScreenplayBuilder.html#CSF_Screenplay_ScreenplayBuilder_ConfigureServices_System_Action_Microsoft_Extensions_DependencyInjection_IServiceCollection__">ConfigureServices(Action&lt;IServiceCollection&gt;)</a>
+to accomplish this.
+</p>
+</div>
 
 
 
@@ -170,7 +185,7 @@ <h4 class="section">Returns</h4>
 </article>
 
         <div class="contribution d-print-none">
-          <a href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay/IGetsScreenplay.cs/#L18" class="edit-link">Edit this page</a>
+          <a href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay/IGetsScreenplay.cs/#L23" class="edit-link">Edit this page</a>
         </div>
 
 

docs/api/CSF.Screenplay.ScreenplayAssemblyAttribute.html

@@ -89,7 +89,7 @@ <h5 class="offcanvas-title" id="tocOffcanvasLabel">Table of Contents</h5>
 
 
   <h1 id="CSF_Screenplay_ScreenplayAssemblyAttribute" data-uid="CSF.Screenplay.ScreenplayAssemblyAttribute" class="text-break">
-Class ScreenplayAssemblyAttribute  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L27"><i class="bi bi-code-slash"></i></a>
+Class ScreenplayAssemblyAttribute  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L31"><i class="bi bi-code-slash"></i></a>
   </h1>
 
   <div class="facts text-secondary">
@@ -262,7 +262,7 @@ <h1 id="CSF_Screenplay_ScreenplayAssemblyAttribute" data-uid="CSF.Screenplay.Scr
 
   <h2 id="CSF_Screenplay_ScreenplayAssemblyAttribute_examples">Examples</h2>
   <p>
-Decorate your assembly with this attribute using the syntax <code>[assembly: ScreenplayAssembly]</code>.  You may place this
+Decorate your assembly with this attribute using the syntax <code>[assembly: CSF.Screenplay.ScreenplayAssembly]</code>.  You may place this
 into any source file, outside of any type declaration.  By convention it would be put into a dedicated source file
 within the <code>Properties</code> project directory.
 </p>
@@ -274,8 +274,11 @@ <h2 id="CSF_Screenplay_ScreenplayAssemblyAttribute_remarks">Remarks</h2>
 In order to run tests with Screenplay, the assembly must be decorated with this attribute.
 </p>
 <p>
-This attribute identifies a concrete implementation of <a class="xref" href="CSF.Screenplay.IGetsScreenplay.html">IGetsScreenplay</a> which will be used to build and retrieve
-the <a class="xref" href="CSF.Screenplay.Screenplay.html">Screenplay</a> instance for running those tests.
+This attribute has one mandatory parameter; that is the <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.type">Type</a> of a concrete implementation of
+<a class="xref" href="CSF.Screenplay.IGetsScreenplay.html">IGetsScreenplay</a>.  That type will be instantiated by the NUnit3 integration and will be used to
+build and retrieve the <a class="xref" href="CSF.Screenplay.Screenplay.html">Screenplay</a> instance for running the Screenplay-based tests within the decorated
+assembly. Each test method must additionally be decorated with the <a class="xref" href="CSF.Screenplay.ScreenplayAttribute.html">ScreenplayAttribute</a> in order to make
+it a Screenplay-based test.
 </p>
 </div>
 
@@ -288,7 +291,7 @@ <h2 class="section" id="constructors">Constructors
 
   <h3 id="CSF_Screenplay_ScreenplayAssemblyAttribute__ctor_System_Type_" data-uid="CSF.Screenplay.ScreenplayAssemblyAttribute.#ctor(System.Type)">
   ScreenplayAssemblyAttribute(Type)
-  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L73"><i class="bi bi-code-slash"></i></a>
+  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L77"><i class="bi bi-code-slash"></i></a>
   </h3>
 
   <div class="markdown level1 summary"><p>Initializes a new instance of <a class="xref" href="CSF.Screenplay.ScreenplayAssemblyAttribute.html">ScreenplayAssemblyAttribute</a>.</p>
@@ -331,7 +334,7 @@ <h2 class="section" id="properties">Properties
 
   <h3 id="CSF_Screenplay_ScreenplayAssemblyAttribute_Targets" data-uid="CSF.Screenplay.ScreenplayAssemblyAttribute.Targets">
   Targets
-  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L51"><i class="bi bi-code-slash"></i></a>
+  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L55"><i class="bi bi-code-slash"></i></a>
   </h3>
 
   <div class="markdown level1 summary"><p>Provides the target for the action attribute</p>
@@ -367,7 +370,7 @@ <h2 class="section" id="methods">Methods
 
   <h3 id="CSF_Screenplay_ScreenplayAssemblyAttribute_AfterTest_NUnit_Framework_Interfaces_ITest_" data-uid="CSF.Screenplay.ScreenplayAssemblyAttribute.AfterTest(NUnit.Framework.Interfaces.ITest)">
   AfterTest(ITest)
-  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L54"><i class="bi bi-code-slash"></i></a>
+  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L58"><i class="bi bi-code-slash"></i></a>
   </h3>
 
   <div class="markdown level1 summary"><p>Executed after each test is run</p>
@@ -400,7 +403,7 @@ <h4 class="section">Parameters</h4>
 
   <h3 id="CSF_Screenplay_ScreenplayAssemblyAttribute_BeforeTest_NUnit_Framework_Interfaces_ITest_" data-uid="CSF.Screenplay.ScreenplayAssemblyAttribute.BeforeTest(NUnit.Framework.Interfaces.ITest)">
   BeforeTest(ITest)
-  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L57"><i class="bi bi-code-slash"></i></a>
+  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L61"><i class="bi bi-code-slash"></i></a>
   </h3>
 
   <div class="markdown level1 summary"><p>Executed before each test is run</p>
@@ -433,7 +436,7 @@ <h4 class="section">Parameters</h4>
 
   <h3 id="CSF_Screenplay_ScreenplayAssemblyAttribute_GetScreenplay" data-uid="CSF.Screenplay.ScreenplayAssemblyAttribute.GetScreenplay">
   GetScreenplay()
-  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L38"><i class="bi bi-code-slash"></i></a>
+  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L42"><i class="bi bi-code-slash"></i></a>
   </h3>
 
   <div class="markdown level1 summary"><p>Gets the <a class="xref" href="CSF.Screenplay.Screenplay.html">Screenplay</a> which is to be used for tests contained in the current assembly.</p>
@@ -469,11 +472,15 @@ <h4 class="section">Exceptions</h4>
 
 
 
+  <h2 id="seealso">See Also</h2>
+  <div class="seealso">
+      <div><a class="xref" href="CSF.Screenplay.ScreenplayAttribute.html">ScreenplayAttribute</a></div>
+  </div>
 
 </article>
 
         <div class="contribution d-print-none">
-          <a href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L27" class="edit-link">Edit this page</a>
+          <a href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAssemblyAttribute.cs/#L31" class="edit-link">Edit this page</a>
         </div>
 
 

docs/api/CSF.Screenplay.ScreenplayAttribute.html

@@ -89,7 +89,7 @@ <h5 class="offcanvas-title" id="tocOffcanvasLabel">Table of Contents</h5>
 
 
   <h1 id="CSF_Screenplay_ScreenplayAttribute" data-uid="CSF.Screenplay.ScreenplayAttribute" class="text-break">
-Class ScreenplayAttribute  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAttribute.cs/#L32"><i class="bi bi-code-slash"></i></a>
+Class ScreenplayAttribute  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAttribute.cs/#L33"><i class="bi bi-code-slash"></i></a>
   </h1>
 
   <div class="facts text-secondary">
@@ -285,7 +285,7 @@ <h2 class="section" id="properties">Properties
 
   <h3 id="CSF_Screenplay_ScreenplayAttribute_Targets" data-uid="CSF.Screenplay.ScreenplayAttribute.Targets">
   Targets
-  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAttribute.cs/#L59"><i class="bi bi-code-slash"></i></a>
+  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAttribute.cs/#L60"><i class="bi bi-code-slash"></i></a>
   </h3>
 
   <div class="markdown level1 summary"><p>Gets the targets for the attribute (when performing before/after test actions).</p>
@@ -322,7 +322,7 @@ <h2 class="section" id="methods">Methods
 
   <h3 id="CSF_Screenplay_ScreenplayAttribute_AfterTest_NUnit_Framework_Interfaces_ITest_" data-uid="CSF.Screenplay.ScreenplayAttribute.AfterTest(NUnit.Framework.Interfaces.ITest)">
   AfterTest(ITest)
-  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAttribute.cs/#L71"><i class="bi bi-code-slash"></i></a>
+  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAttribute.cs/#L72"><i class="bi bi-code-slash"></i></a>
   </h3>
 
   <div class="markdown level1 summary"><p>Executed after each test is run</p>
@@ -355,7 +355,7 @@ <h4 class="section">Parameters</h4>
 
   <h3 id="CSF_Screenplay_ScreenplayAttribute_BeforeTest_NUnit_Framework_Interfaces_ITest_" data-uid="CSF.Screenplay.ScreenplayAttribute.BeforeTest(NUnit.Framework.Interfaces.ITest)">
   BeforeTest(ITest)
-  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAttribute.cs/#L63"><i class="bi bi-code-slash"></i></a>
+  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAttribute.cs/#L64"><i class="bi bi-code-slash"></i></a>
   </h3>
 
   <div class="markdown level1 summary"><p>Executed before each test is run</p>
@@ -388,7 +388,7 @@ <h4 class="section">Parameters</h4>
 
   <h3 id="CSF_Screenplay_ScreenplayAttribute_BuildFrom_NUnit_Framework_Interfaces_IMethodInfo_NUnit_Framework_Internal_Test_" data-uid="CSF.Screenplay.ScreenplayAttribute.BuildFrom(NUnit.Framework.Interfaces.IMethodInfo,NUnit.Framework.Internal.Test)">
   BuildFrom(IMethodInfo, Test)
-  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAttribute.cs/#L81"><i class="bi bi-code-slash"></i></a>
+  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAttribute.cs/#L82"><i class="bi bi-code-slash"></i></a>
   </h3>
 
   <div class="markdown level1 summary"><p>Build one or more TestMethods from the provided MethodInfo.</p>
@@ -426,11 +426,15 @@ <h4 class="section">Returns</h4>
 
 
 
+  <h2 id="seealso">See Also</h2>
+  <div class="seealso">
+      <div><a class="xref" href="CSF.Screenplay.ScreenplayAssemblyAttribute.html">ScreenplayAssemblyAttribute</a></div>
+  </div>
 
 </article>
 
         <div class="contribution d-print-none">
-          <a href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAttribute.cs/#L32" class="edit-link">Edit this page</a>
+          <a href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay.NUnit/ScreenplayAttribute.cs/#L33" class="edit-link">Edit this page</a>
         </div>
 
 

docs/api/CSF.Screenplay.ScreenplayBuilder.html

@@ -175,7 +175,7 @@ <h2 class="section" id="constructors">Constructors
 
   <h3 id="CSF_Screenplay_ScreenplayBuilder__ctor_Microsoft_Extensions_DependencyInjection_IServiceCollection_" data-uid="CSF.Screenplay.ScreenplayBuilder.#ctor(Microsoft.Extensions.DependencyInjection.IServiceCollection)">
   ScreenplayBuilder(IServiceCollection)
-  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay/ScreenplayBuilder.cs/#L181"><i class="bi bi-code-slash"></i></a>
+  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay/ScreenplayBuilder.cs/#L207"><i class="bi bi-code-slash"></i></a>
   </h3>
 
   <div class="markdown level1 summary"><p>Initialises a new instance of the <a class="xref" href="CSF.Screenplay.ScreenplayBuilder.html">ScreenplayBuilder</a>.</p>
@@ -267,6 +267,61 @@ <h4 class="section">Exceptions</h4>
 
 
 
+  <a id="CSF_Screenplay_ScreenplayBuilder_ConfigureServices_" data-uid="CSF.Screenplay.ScreenplayBuilder.ConfigureServices*"></a>
+
+  <h3 id="CSF_Screenplay_ScreenplayBuilder_ConfigureServices_System_Action_Microsoft_Extensions_DependencyInjection_IServiceCollection__" data-uid="CSF.Screenplay.ScreenplayBuilder.ConfigureServices(System.Action{Microsoft.Extensions.DependencyInjection.IServiceCollection})">
+  ConfigureServices(Action&lt;IServiceCollection&gt;)
+  <a class="header-action link-secondary" title="View source" href="https://github.com/csf-dev/CSF.Screenplay/blob/master/CSF.Screenplay/ScreenplayBuilder.cs/#L171"><i class="bi bi-code-slash"></i></a>
+  </h3>
+
+  <div class="markdown level1 summary"><p>Configures further services into the <a class="xref" href="https://learn.microsoft.com/dotnet/api/microsoft.extensions.dependencyinjection.iservicecollection">IServiceCollection</a> which is contained within the current builder.</p>
+</div>
+  <div class="markdown level1 conceptual"></div>
+
+  <div class="codewrapper">
+    <pre><code class="lang-csharp hljs">public ScreenplayBuilder ConfigureServices(Action&lt;IServiceCollection&gt; configurationAction)</code></pre>
+  </div>
+
+  <h4 class="section">Parameters</h4>
+  <dl class="parameters">
+    <dt><code>configurationAction</code> <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.action-1">Action</a>&lt;<a class="xref" href="https://learn.microsoft.com/dotnet/api/microsoft.extensions.dependencyinjection.iservicecollection">IServiceCollection</a>&gt;</dt>
+    <dd><p>Logic which may be used to perform further configuration upon the service collection.</p>
+</dd>
+  </dl>
+
+  <h4 class="section">Returns</h4>
+  <dl class="parameters">
+    <dt><a class="xref" href="CSF.Screenplay.ScreenplayBuilder.html">ScreenplayBuilder</a></dt>
+    <dd><p>The same builder instance, so that calls may be chained.</p>
+</dd>
+  </dl>
+
+
+
+
+
+
+
+  <h4 class="section" id="CSF_Screenplay_ScreenplayBuilder_ConfigureServices_System_Action_Microsoft_Extensions_DependencyInjection_IServiceCollection___remarks">Remarks</h4>
+  <div class="markdown level1 remarks"><p>
+Use this method to add service descriptors to the service collection for services which are not directly part of the Screenplay
+architecture, but which you wish to access from Screenplay.
+Most often these will be types and services which will be used as (or by) <a class="xref" href="../glossary/Ability.html">Screenplay abilities</a>.
+</p>
+<p>
+Abilities added to dependency injection in this way may be constructor-injected into <a class="xref" href="CSF.Screenplay.IPersona.html">IPersona</a> implementations.
+</p>
+</div>
+
+  <h4 class="section">Exceptions</h4>
+  <dl class="parameters">
+    <dt><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.argumentnullexception">ArgumentNullException</a></dt>
+    <dd><p>If <code class="paramref">configurationAction</code> is <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null">null</a>.</p>
+</dd>
+  </dl>
+
+
+
   <a id="CSF_Screenplay_ScreenplayBuilder_WithCast_" data-uid="CSF.Screenplay.ScreenplayBuilder.WithCast*"></a>
 
   <h3 id="CSF_Screenplay_ScreenplayBuilder_WithCast_System_Func_System_IServiceProvider_CSF_Screenplay_ICast__" data-uid="CSF.Screenplay.ScreenplayBuilder.WithCast(System.Func{System.IServiceProvider,CSF.Screenplay.ICast})">