Merge branch 'feature/docsmigration' of https://github.com/MrValentin…

…e7777/docs.monogame.github.io into DocReviews

.github/workflows/main.yml

@@ -1,10 +1,10 @@
-name: Build Documentation
+name: Build and Deploy Documentation
 on:
-    push:
-        branches:
-            - 'main'
+  push:
+    branches:
+      - 'main'
 
-    workflow_dispatch:
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -18,36 +18,36 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-    build:
-        environment:
-          name: github-pages
-          url: ${{ steps.deployment.outputs.page_url }}
-        runs-on: ubuntu-latest
-        steps:
-            - name: Clone Repository
-              uses: actions/checkout@v4
-              with:
-                submodules: recursive
-
-            - name: Setup .NET SDK
-              uses: actions/setup-dotnet@v4
-              with:
-                dotnet-version: '8.0.x'
-
-            - name: Restore dotnet tools
-              run: dotnet tool restore
-
-            - name: Run Build
-              run: dotnet docfx docfx.json
-
-            - name: Setup Pages
-              uses: actions/configure-pages@v5
-
-            - name: Upload artifact
-              uses: actions/upload-pages-artifact@v3
-              with:
-                path: '_site'
-
-            - name: Deploy to GitHub Pages
-              id: deployment
-              uses: actions/deploy-pages@v4
+  build:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone Repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '8.0.x'
+
+      - name: Restore dotnet tools
+        run: dotnet tool restore
+
+      - name: Run Build
+        run: dotnet docfx docfx.json
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_site'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/pullrequest.yml

@@ -0,0 +1,47 @@
+name: Test Build Documentation
+
+on:
+  pull_request:
+    branches:
+      - 'main'
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write           
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    concurrency: ci-${{ github.ref }}
+    steps:
+      - name: Clone Repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '8.0.x'
+
+      - name: Restore dotnet tools
+        run: dotnet tool restore
+
+      - name: Run Build
+        run: dotnet docfx docfx.json
+
+  complete:
+    runs-on: ubuntu-latest
+    needs: test
+    name: Test completion task
+    steps:
+      - run: echo "Tests Complete"

README.md

@@ -17,10 +17,10 @@ With your environment setup properly, the following explains how to build from s
     git clone https://github.com/MonoGame/monogame.github.io.git
     ```
 
-2. Install npm dependencies
+2. Install DotNet dependencies
 
     ```sh
-    npm install
+    dotnet tool restore
     ```
 
 3. Optional Steps
@@ -29,10 +29,13 @@ With your environment setup properly, the following explains how to build from s
 
    `git submodule update --init --recursive`
 
-4. Run a local build and serve it with hot reloading.  The site is full DocFX now so a single build command will do:
+4. Run a local build and serve it. The site is full DocFX now so a single build command will do:
 
   `dotnet docfx docfx.json --serve`
 
+> [!NOTE]
+> Docfx hosting does not support hot reload, so to refresh the hosted site you will need to stop the agent (ctrl-c) and run the above command again to refresh pages
+
 ## Document styling
 
 The use of DocFX with the updated MonoGame docs site has afforded the use of some custom stylings to improve consistency and more stylized docs:
@@ -53,6 +56,9 @@ The use of DocFX with the updated MonoGame docs site has afforded the use of som
 
 As an example of a document written using the above notes, please refer to the [HowTo: Create a Render Target tutorial](https://github.com/MonoGame/docs.monogame.github.io/blob/feature/docsmigration/articles/monogame/howto/graphics/HowTo_Create_a_RenderTarget.md)
 
+> [!TIP]
+> No additional text is needed at the bottom of document pages as the licenses and requirements are automatically added by the DocFX build system
+
 ## LICENSE
 
 The MonoGame project is under the Microsoft Public License except for a few portions of the code. See the [LICENSE](LICENSE) file for more details.

api/index.md

@@ -7,4 +7,4 @@ Welcome to the **MonoGame** reference documentation!
 
 This area provides detailed information on each class and method in the API.
 
-Please view the [documentation](../articles/) for how to get started and step-by-step guidance.
+Please view the [documentation](../articles/index.md) for how to get started and step-by-step guidance.

articles/getting_started/1_setting_up_your_development_environment_unix.md

@@ -58,7 +58,7 @@ sudo apt install wine64 p7zip-full curl
 Create wine prefix:
 
 ```sh
-wget -qO- https://raw.githubusercontent.com/MonoGame/MonoGame/master/Tools/MonoGame.Effect.Compiler/mgfxc_wine_setup.sh | bash
+wget -qO- https://monogame.net/downloads/net6_mgfxc_wine_setup.sh | bash
 ```
 
 If you ever need to undo the script, simply delete the `.winemonogame` folder in your home directory.

articles/getting_started/1_setting_up_your_development_environment_windows.md

@@ -18,16 +18,17 @@ Before using MonoGame, you will need to install [Visual Studio 2022](https://vis
 When installing Visual Studio, the following workloads are required depending on your desired [target platform(s)](../platforms.md):
 
 * Mandatory for all platforms:
-    * **.Net desktop development**
+  * **.Net desktop development**
 * Optional
-    * **.Net Multi-platform App UI Development** if you wish to target Android, iOS, or iPadOS.
-    * **Universal Windows Platform development** if you wish to build for Windows store or Xbox.
+  * **.Net Multi-platform App UI Development** if you wish to target Android, iOS, or iPadOS.
+  * **Universal Windows Platform development** if you wish to build for Windows store or Xbox.
 
 ![Visual Studio optional components](images/1_installer_vs_components.png)
 
-::: danger Targeting Windows
-If you are targeting the standard Windows DirectX backend, you will also need [the DirectX June 2010 runtime](https://www.microsoft.com/en-us/download/details.aspx?id=8109) for audio and gamepads to work properly.
-:::
+> [!WARNING]
+> **Targeting Windows**
+>
+> If you are targeting the standard Windows DirectX backend, you will also need [the DirectX June 2010 runtime](https://www.microsoft.com/en-us/download/details.aspx?id=8109) for audio and gamepads to work properly.
 
 ### Install MonoGame extension for Visual Studio 2022
 
@@ -46,7 +47,6 @@ To create new MonoGame projects from within Visual Studio 2022, you will need to
 
 ![Visual Studio Extension Manager](images/1_visual_studio_extension_manager.png)
 
-
 5. After it is downloaded, an alert will appear at the bottom of the Manage Extensions window that states "Your changes will be scheduled.  The modifications will begin when all Microsoft Visual Studio windows are closed."  Click the **Close** button, then close Visual Studio 2022.
 
 6. After closing Visual Studio 2022, a VSIX Installer window will open confirming that you want to install the **MonoGame Framework C# project templates** extension.  Click the **Modify** button to accept the install.

articles/monogame/howto/audio/HowTo_ChangePitchAndVolume.md

@@ -1,18 +1,17 @@
 ---
 title: How to adjust Pitch and Volume
 description: Demonstrates how to manipulate the pitch and volume of sound effects as they play.
+requireMSLicense: true
 ---
 
-# Adjusting Pitch and Volume
-
 The **[SoundEffect.Play](xref:Microsoft.Xna.Framework.Audio.SoundEffect.Play)** method allows you to specify the pitch and volume of a sound to play. However, after you call **[Play](xref:Microsoft.Xna.Framework.Audio.SoundEffect.Play)**, you cannot modify the sound. Using **[SoundEffectInstance](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance)** for a given **[SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect)** allows you to change the **pitch** and **volume** of a sound at any time during playback.
 
 > [!NOTE]
 > The pitch of a sound changes the frequency of the sound, which in turn changes the speed of the sound. The volume of a sound changes the amplitude of the sound, which in turn changes the loudness of the sound.
 
 ## Change Pitch and Volume of Sound
 
-1. Declare a **[SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect)** and a [Stream](http://msdn.microsoft.com/en-us/library/system.io.stream.aspx) file by using the method shown in [Playing a Sound](HowTo_PlayASound.md). In addition to the method described in [Playing a Sound](HowTo_PlayASound.md), declare a **[SoundEffectInstance](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance)**, we also add a **Sound Effect** field member. We also create two float fields for **pitch** and **volume** to store the pitch and volume of the sound effect and assign initial values to them.
+1. Declare a **[SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect)** and a [Stream](http://msdn.microsoft.com/en-us/library/system.io.stream.aspx) file by using the method shown in [Playing a Sound](HowTo_PlayASound.md). In addition to the method described in [Playing a Sound](HowTo_PlayASound.md), declare a **[SoundEffectInstance](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance)** and a **Sound Effect** field member. We also create two float fields for **pitch** and **volume** to store the pitch and volume of the sound effect and assign initial values to them.
 
     ```csharp
     // place these usings at the top of the file
@@ -29,65 +28,44 @@ The **[SoundEffect.Play](xref:Microsoft.Xna.Framework.Audio.SoundEffect.Play)**
     private float volume = 0.5f;
     ```
 
-> [!NOTE]
-> Usings are declared at the top of the file to ensure that the necessary namespaces are available to the class. The fields are declared at the top of the class to ensure that they are accessible to all methods in the class.
+    > [!NOTE]
+    > Usings are declared at the top of the file to ensure that the necessary namespaces are available to the class. The fields are declared at the top of the class to ensure that they are accessible to all methods in the class.
+
+2. In the [Game.LoadContent](xref:Microsoft.Xna.Framework.Game.LoadContent) method, set the **SoundEffectInstance** object to the return value of [SoundEffect.CreateInstance](xref:Microsoft.Xna.Framework.Audio.SoundEffect.CreateInstance).
 
-2. In the **[Game.LoadContent](xref:Microsoft.Xna.Framework.Game.LoadContent)** method, set the **SoundEffectInstance** object to the return value of **[SoundEffect.CreateInstance](xref:Microsoft.Xna.Framework.Audio.SoundEffect.CreateInstance)**. We also optionally define a variable **soundFile** to store the location of the sound file being used with the **[TitleContainer.OpenStream](xref:Microsoft.Xna.Framework.TitleContainer.OpenStream)** method, which is accessed with the  **using** keyword, and include a field member variable called **soundEffect**, to hold the stream.
+3. In the **[Game.LoadContent](xref:Microsoft.Xna.Framework.Game.LoadContent)** method, set the **SoundEffectInstance** object to the return value of **[SoundEffect.CreateInstance](xref:Microsoft.Xna.Framework.Audio.SoundEffect.CreateInstance)**. We also optionally define a variable **soundFile** to store the location of the sound file being used with the **[TitleContainer.OpenStream](xref:Microsoft.Xna.Framework.TitleContainer#Microsoft_Xna_Framework_TitleContainer_OpenStream_System_String_)** method, which is accessed with the  **using** keyword, and include a field member variable called **soundEffect**, to hold the stream.
 
     ```csharp
     using Stream soundfile = TitleContainer.OpenStream(@"Content\Sound__FileName.wav");
     soundEffect = SoundEffect.FromStream(soundfile);
     soundInstance = soundEffect.CreateInstance();
     ```
 
-> [!NOTE]
-> The **using** statement is used to ensure that the stream is disposed of correctly after the sound effect has been loaded. The **TitleContainer.OpenStream** method is used to open a stream to the sound file, which is then used to create a **SoundEffect** object. The **SoundEffect.CreateInstance** method is used to create a **SoundEffectInstance** object from the **SoundEffect** object.
-
-> [!CAUTION]
-> Ensure the file name is correct and the file is in the correct location. The file name should be the name of the sound file you are using and include the extention of the file. The file should be in the Content folder of the project otherwise an error will be thrown. Also ensure you set the **Copy if newer** property of the sound file within the IDE to ensureit is copied to the output directory and set the build action to **Content**.
-
-3. Remaining in the **Game.LoadContent**  method, adjust the sound to the desired levels using the **SoundEffectInstance.Pitch** and **SoundEffectInstance.Volume** properties if not already assigned. The pitch and volume values are set to the values of the **pitch** and **volume** fields respectively.
-
-    ```csharp
-    // Pitch takes values from -1 to 1 as a float value    
-    // for example 0.5f is half the pitch of the original sound
-    // and 0.25f is a quarter of the pitch of the original sound    
-    // -0.25f is a quarter of the pitch of the original sound
-    // in the opposite direction
-    // this will play the sound in reverse at a quarter of the speed
-    soundEffectInstance.Pitch = pitch;
-
-    // Volume only takes values from 0 to 1 as a float value
-    soundEffectInstance.Volume = volume;
-    ```
-
-> [!TIP]
-> You can adjust the pitch and volume values at any time throughout your code, ideally you may assign a global sound value to the volume value, to allow the user to adjust the volums within a single menu, which affects sounds in the entire program.
-
-4. Still in the **Game.LoadContent** method, call the **SoundEffectInstance.Play** method to play the sound effect.
+4. Adjust the sound to the desired level using the [SoundEffectInstance.Pitch](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance.Pitch) and [SoundEffectInstance.Volume](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance.Volume) properties.
 
     ```csharp
-    // Play the sound effect instance
+    // Play Sound
     soundEffectInstance.Play();
     ```
 
-> [!NOTE]
-> An instance will play once, to loop the sound, you can use the **[SoundEffectInstance.IsLooped](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance.IsLooped)** property to set the sound to loop. Also note that the sound will not repeat until the sound has finished playing. You can utilise the **[SoundEffectInstance.State](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance.State)** property to check if the sound is playing, paused or stopped. Use the **[SoundEffectInstance.Stop](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance.Stop)** method to stop the sound.
+     > [!NOTE]
+     > An instance will play once, to loop the sound, you can use the **[SoundEffectInstance.IsLooped](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance.IsLooped)** property to set the sound to loop. Also note that the sound will not repeat until the sound has finished playing. You can utilise the **[SoundEffectInstance.State](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance.State)** property to check if the sound is playing, paused or stopped. Use the **[SoundEffectInstance.Stop](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance.Stop)** method to stop the sound.
 
 ## An Extended Example
 
-5. Below the **[Game.Draw](xref:Microsoft.Xna.Framework.Game.Draw)** method, create a new method called **IsKeyPressed**, which will check if a specified key is pressed and return a boolean value of true if it has been pressed.
+ 1. Below the **[Game.Draw](xref:Microsoft.Xna.Framework.Game#Microsoft_Xna_Framework_Game_Draw_Microsoft_Xna_Framework_GameTime_)** method, create a new method called **IsKeyPressed**, which will check if a specified key is pressed and return a boolean value of true if it has been pressed.
 
     ```csharp
     private bool IsKeyPressed(Keys key)
     {
         return Keyboard.GetState().IsKeyDown(key);
     }
-    ```
 
-6. In the **[Game.Update](xref:Microsoft.Xna.Framework.Game.Update)** method, check if the **Space** key is pressed and adjust the pitch and volume of the sound effect accordingly. The pitch and volume values are adjusted by +0.1f each time the **Space key** is pressed. The pitch values are clamped to a minimum value of -1.0f and a maximum value of 1.0f, and the volume values are then clamped to a minimum value of 0f and a maximum value of 1.0f. This is done to ensure that the pitch and volume values are within  valid ranges.
+     ```
 
-    ```csharp
+ 2. In the **[Game.Update](xref:Microsoft.Xna.Framework.Game#Microsoft_Xna_Framework_Game_Update_Microsoft_Xna_Framework_GameTime_)** method, check if the **Space** key is pressed and adjust the pitch and volume of the sound effect accordingly. The pitch and volume values are adjusted by +0.1f each time the **Space key** is pressed. The pitch values are clamped to a minimum value of -1.0f and a maximum value of 1.0f, and the volume values are then clamped to a minimum value of 0f and a maximum value of 1.0f. This is done to ensure that the pitch and volume values are within  valid ranges.
+
+ ```csharp
     // Check if the SpaceKey is pressed and play the instance
     if (IsKeyPressed(Keys.Space))
         {
@@ -99,7 +77,7 @@ The **[SoundEffect.Play](xref:Microsoft.Xna.Framework.Audio.SoundEffect.Play)**
          soundEffectInstance.Volume = volume;
          soundEffectInstance.Play();
         }
-    ```
+ ```
 
  > [!NOTE]
  > The **MathHelper.Clamp** method is used to ensure that the pitch and volume values are within the valid range. The pitch value is clamped between -1 and 1, while the volume value is clamped between 0 and 1.
@@ -130,9 +108,3 @@ Provides a loaded sound resource.
 [SoundEffectInstance Class](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance)
 
 Provides a single playing, paused, or stopped instance of a [SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect) sound.
-
----
-
-© 2012 Microsoft Corporation. All rights reserved.  
-
-© 2024 The MonoGame Foundation.