Merge pull request #988 from pkbullock/dev

Updated the docs for polyglot setup

docs/using-the-framework/readme.md

@@ -35,32 +35,26 @@ dotnet add package PnP.Framework --version 1.13.xx-nightly
 
 Each night these preview packages are refreshed, so you can always upgrade to the latest dev bits by upgrading your NuGet package to the latest version.
 
-## Using PolyGlot Notebooks
+## Samples use PolyGlot Notebooks
 
-The PolyGlot samples provide working examples of how to interact with SharePoint, that can be ran against your Microsoft 365 tenant, written in C#.
+The PolyGlot samples provide working examples of how to interact with SharePoint, that can be ran against your Microsoft 365 tenant, written in C# and runnable code - as an aid to understand and learning of how to use the PnP Framework.
 
+The simplest way to get working samples, is to check out the notebooks in our repo, please navigate to the [GitHub repository](https://github.com/pnp/pnpframework/tree/dev/docs/notebooks), the following notebooks are available, to use these, you will need to *clone the repository* and open the notebooks in Visual Studio Code, using the [Extension - PolyGlot Notebooks by Microsoft](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-interactive-vscode).
 
-```dotnetcli
-#r "nuget: PnP.Framework, 1.13.xx-nightly"
-```
-
-
-The simplest way to get working samples, is to check out the notebooks, please navigate to the GitHub repository, the following notebooks are available, to use these, you will need to *clone the repository* and open the notebooks in Visual Studio Code, using the [Extension - PolyGlot Notebooks by Microsoft](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-interactive-vscode).
-
+To get setup, please follow the instructions in the [Setting up to use Polyglot samples](setting-up-to-use-polyglot-samples.md) guide.
 
 Examples:
 
 - [Getting Started with the PnP Framework | PolyGlot Notebook](https://github.com/pnp/pnpframework/tree/dev/docs/notebooks/Getting-Started-with-PnP-Framework.ipynb)
 - [Getting Started with the PnP Provisioning | PolyGlot Notebook](https://github.com/pnp/pnpframework/tree/dev/docs/notebooks/Getting-Started-with-PnP-Provisioning.ipynb)
 
 
-> [!Note]
-> These are a work in progress to provider richer samples, but these take a while to write. If you have any suggestions or wish to contribute your examples, please raise an issue in the GitHub repository.
+_*Note: These are a work in progress to provider richer samples, but these take a while to write. If you have any suggestions or wish to contribute your examples, please raise an issue in the GitHub repository._
 
 If you feel samples should be present in the documentation, please [raise an issue in the GitHub repository](https://github.com/pnp/pnpframework/issues), and lets discuss your thoughts.
 
 
-## If you want to know how PnP Framework is build, here is the code?
+## If you want to know how PnP Framework is built, here is the code?
 
 The PnP Framework is maintained in the PnP GitHub repository: https://github.com/pnp/pnpframework. You'll find:
 

docs/using-the-framework/setting-up-to-use-polyglot-samples.md

@@ -14,6 +14,10 @@ The Polyglot Notebooks are designed to be run against your tenant, but you will
 
 ### Settings File
 
+ For these notebooks, we are using the PnP Framework to authenticate with SharePoint using the certificate. You will need to create an Azure AD App Registration and generate a certificate, assign permissions to SharePoint within the app.
+
+To setup the app quickly, we recommend using PnP PowerShell to create the app registration and certificate - https://pnp.github.io/powershell/articles/authentication.html
+
 To keep credentials away from the PolyGlot Notebooks, we have setup a seperate file to contain these, copy the `appsettings.sample.json` file to `appsettings.json` and update the values to match your environment.
 
 ```json
@@ -27,11 +31,32 @@ To keep credentials away from the PolyGlot Notebooks, we have setup a seperate f
 
 ```
 
-You will need to create an Azure AD App Registration and generate a certificate, assign permissions to SharePoint within the app. For these notebooks, we have kept access to this for the time being.
+Complete each variable in the `appsettings.json` file with the following values:
+
+- **azureAppId**: This variable represents the Azure AD App ID. You will need to create an Azure AD App Registration and obtain the App ID for your application.
+- **certificatePassword**: This variable represents the password for the certificate used by the Azure AD App Registration. You will need to generate a certificate and provide the corresponding password.
+- **certificatePath**: This variable represents the file path to the certificate used by the Azure AD App Registration. You will need to provide the correct file path where the certificate is located on your system.
+- **azureTenantName**: This variable represents the name of your Azure AD tenant. You will need to provide the name of your Azure AD tenant (e.g., contoso.onmicrosoft.com).
+- **siteUrl**: This variable represents the URL of your SharePoint site. You will need to provide the URL of your SharePoint site (e.g., https://contoso.sharepoint.com/sites/contoso).
 
+Make sure to replace app-id, cert-password, and other placeholder values with the actual values specific to your environment.
 
-*There is more coming on how to do this.*
 
 ## Running the Notebooks
 
-...
+Once you have configured the settings file, navigate to the [PnP Framework | GitHub](https://github.com/pnp/pnpframework) repository, ensure you have setup a local version with git clone and open the `docs/notebooks` folder in Visual Studio Code. You will find some sample notebooks in this folder. Open the notebook you want to run and click the "Run All Cells" button to run the entire notebook. You can also run individual cells by clicking the "Run Cell" button.
+
+![Image of screenshot of Polyglot setup](../images/polyglot-running-screenshot.png)
+
+Overtime these samples will grow and you can explore the framework, experiment and learn how to use the PnP Framework within your own projects.
+
+## Updating the version of PnP Framework
+
+```dotnetcli
+#r "nuget: PnP.Framework, 1.13.xx-nightly"
+```
+
+The code #r "nuget: PnP.Framework, 1.13.xx-nightly" is using the dotnetcli language specifier to specify a NuGet package reference in a .NET Interactive Notebook. It is referencing the PnP.Framework package with version 1.13.xx-nightly. This code is instructing the notebook to import the PnP.Framework package, making its functionality available for use in the notebook.
+
+This may not reflect the latest version of the PnP Framework, so you can update the version of the PnP Framework by changing the version number in the code. You can find the latest version of the PnP Framework on the [PnP.Framework Package | Nuget](https://www.nuget.org/packages/PnP.Framework) page.
+