Onboarding Powershell Project

Following are 3 possible scenarios:

  1. Onboard a brand new powershell portfolio - New docset
  2. Onboard a new version within existing service and existing docset
  3. Onboard a new service within existing docset

Onboard a brand new powershell portfolio - New docset

Step 1: Set up Docs repo

Thru OPS portal, Set up a repo (Microsoftdocs/xxx-docs-powershell) and provision a docset to publish to /powershell/ABC in docs.microsoft.com.

Next, set up the following structure in the repo and add cmdlets markdowns accordingly. If there is no version create a 'vlatest' folder within the module folder and add the cmdlets.

REPOROOT
|   Folder_Name
|       Module_A_Name
|           Version
|               cmdlet.md
|               cmdlet.md
|       Module_B_Name
|               cmdlet.md
|               cmdlet.md
|       Docs-conceptual
|       mapping
|       docfx.json
|   README.md(optional)

Examples could be found in below repos:

Add all the conceptual docs to the 'docs-conceptual' folder inclduing a toc.md file.

Note

If you have version specific conceptual content then create the version folders and add TOC.md applicable to the specific versions. Look at Azure powershell repo for reference.

Step 2: Enable share base path

Email Zhiliang Xu/Yannan Wang to change base path from /powershell/ABC to /powershell

Step 3: Set up monikers

This step can only be done by Engagement PMs. Identify the right monikers and get them created. For details on moniker refer to this topic

Step 4: Set up Configuration in repo

OPS initiates required configuration files during provision, including .openpushing.publish.config.json, docfx.json. These files need to be udpated once a moniker is available. Ensure to validate the json files before checking in is encouraged.

Moniker mapping file

Moniker mapping file is JSON formatted, which is used to indicate which modules should be included in a particular moniker. Here's the schema:

Value wrapped in <> means it's required, and wrapped in [] means it's optional. Note that, relative path means that the path is relative to repo.

{
    "<name of moniker>": {
        "conceptualToc": "<relative path of toc.md for conceptual>",
        "serviceMap": "[relative path of service mapping file for the moniker]",
        "packageRoot": "<relative path of folder that contains modules>",
        "modules": {
            "<name of module folder>": {
                "_displayName": "[display name of the module]",
                "_version": "[name of version folder]",
                "_path": "[relative path of the module]"
            },
            ...
        }
    },
    ...
}
  • If serviceMap is not set, we'll use module name in TOC under reference.
  • If _displayName is not set, we'll use name of module folder as the display name.
  • If _version is not set, we'll copy files under the module folder directly.
  • If _path is not set, the path of module folder would equal to path combined by packageRoot and name of module folder.

Here is an example:

{
    "azuresmps-4.0.0": {
        "conceptualToc": "azureps-cmdlets-docs/ServiceManagement/docs-conceptual/TOC.md",
        "serviceMap": "azureps-cmdlets-docs/ServiceManagement/mapping/groupMapping-4.0.0.json",
        "packageRoot": "azureps-cmdlets-docs/ServiceManagement",
        "modules": {
            "Azure": {
                "_displayName": "Azure",
                "_version": "v4.0.0"
            },
            "AzureRM.Profile": {
                "_displayName": "AzureRM.Profile",
                "_version": "v3.0.0"
            },
            "Azure.Storage": {
                "_displayName": "Azure.Storage",
                "_version": "v3.0.0"
            }
        }
},

Validate the json file and add to 'mapping' folder within the repo.

Update docfx.json

This section will focus on how to update docfx.json for powershell documentation with moniker.

Note

There's a key named version in docfx.json which has the same meaning of moniker here. For every content section, we need to specify the version of it. The value of section should be the name of moniker.

  1. Within the Content section of build, set up the configuration as per example below:

    For the below example, all the three content sections belongs to moniker azureipps.

    {
    "build": {
     "content": [
       {
         "files": [
           "**/*.md"
         ],
         "src": "azureipps/docs-conceptual",
         "version": "azureipps",
         "dest": "azure/azureipps"
       },
       {
         "files": [
           "**/*.md"
         ],
         "src": "azureipps",
         "version": "azureipps",
         "exclude": [
           "docs-conceptual/**"
         ],
         "dest": "module"
       },
       {
         "files": [
           "toc.yml"
         ],
         "src": "azureipps",
         "version": "azureipps",
         "dest": "module/azureipps"
       }
     ]
    }
    }
    
  • The first content section includes conceptual markdown files. src should always be <moniker>/docs-conceptual.
  • The second content section includes reference markdown files. src should always be <moniker> and exclude docs-conceptual/**.
  • The third content section includes reference toc.yml generated automatically by plugin.
  1. Add a section versions within build configuration, which tells DocFX where the version should be saved. json "versions": { "azureipps": { "dest": "azureipps" } }
Note

In the backend, AzurePSPlugin will generate reference toc.yml according to the moniker mapping file automatically, and save it in <repo_root>/<moniker_name>/toc.yml. So please include it in content section of docfx.json.

As for the dest of toc, it's up to your decision. However, suggestion is to set it with module/<moniker_name> for the generated >toc, as you can see from above docfx.json example.

  1. Within the global metadata add "showPowerShellPicker": "true" to enable PowerShell picker for monikers and also all applicable BI metadata.

Update .openpublishing.publish.config.json

There are some configurations that MUST to be added to this file. Use (this file)[https://github.com/MicrosoftDocs/office-powershell-docs/blob/master/.openpublishing.publish.config.json] for reference.

  1. Within the type_mapping: add mapping "AzurePSModulePage": "Content" in this section.
  2. Add section customized_template_paths section with value ["_dependentPackages/azurecli.plugins/azurecli"].
  3. Add section customized_tasks: add two customized tasks below

    "customized_tasks": {
      "docset_prebuild": [
        "_dependentPackages/Microsoft.OpenPublishing.AzurePSPlugin/tools/Restructure.ps1"
      ]
    }
    
  4. Within dependent_packages: add 2 dependent packages: opbuild.templates.azurecli, Microsoft.OpenPublishing.AzurePSPlugin.

    "dependent_packages": [
      {
        "path_to_root": "_dependentPackages/azurecli.plugins",
        "id": "opbuild.templates.azurecli",
        "version": "latest",
        "nuget_feed": "https://www.myget.org/F/op/api/v2"
      },
      {
        "id": "Microsoft.OpenPublishing.AzurePSPlugin",
        "path_to_root": "_dependentPackages/Microsoft.OpenPublishing.AzurePSPlugin",
        "version": "latest-prerelease",
        "nuget_feed": "https://www.myget.org/F/op-dev/api/v2"
      }
    ]
    
  5. Add a new section monikerPath: and include the path of moniker mapping file. if there are multiple then add all the paths. This is the input config for Microsoft.OpenPublishing.AzurePSPlugin.

Here is an example:

{
  "build_entry_point": "docs",
  "need_generate_pdf": false,
  "need_generate_intellisense": false,
  "docsets_to_publish": [
    {
      "docset_name": "azureps-azuread",
      "build_source_folder": ".",
      "build_output_subfolder": "azureps-azuread",
      "locale": "en-us",
      "monikers": [],
      "open_to_public_contributors": true,
      "git_repository_branch_open_to_public_contributors": "master",
      "type_mapping": {
        "Conceptual": "Content",
        "ManagedReference": "Content",
        "RestApi": "Content",
        "AzurePSModulePage": "Content"
      },
      "build_entry_point": "docs",
      "template_folder": "_themes",
      "version": 0,
      "monikerPath": [
        "Azure AD Cmdlets/mapping/monikerMapping.json"
      ],
      "customized_template_paths": [
        "_dependentPackages/azurecli.plugins/azurecli"
      ],
      "customized_tasks": {
        "docset_prebuild": [
          "_dependentPackages/Microsoft.OpenPublishing.AzurePSPlugin/tools/Restructure.ps1"
        ]
      }
    }
  ],
  "notification_subscribers": [],
  "branches_to_filter": [],
  "skip_source_output_uploading": false,
  "dependent_repositories": [
    {
      "path_to_root": "_themes",
      "url": "https://github.com/Microsoft/templates.docs.msft",
      "branch": "master",
      "branch_mapping": {}
    }
  ],
  "dependent_packages": [
    {
      "path_to_root": "_dependentPackages/azurecli.plugins",
      "id": "opbuild.templates.azurecli",
      "version": "latest",
      "nuget_feed": "https://www.myget.org/F/op/api/v2"
    },
    {
      "id": "Microsoft.OpenPublishing.AzurePSPlugin",
      "path_to_root": "_dependentPackages/Microsoft.OpenPublishing.AzurePSPlugin",
      "version": "latest-prerelease",
      "nuget_feed": "https://www.myget.org/F/op-dev/api/v2"
    }
  ],
  "need_generate_pdf_url_template": false,
  "dest": "_site"
}

Create breadcrumb.json

Add "breadcrumb.json" to the resources, set the globalMetadata with correct breadcrumb path, set other necessary metadatas. Usually, the breadcrumb path would be /url_set_in_provision/breadcrumb.json.

File breadcrumb.json describes the toc of the site. The default root level toc is Docs. Set nested toc node name and level, href value and homepage under the root level to specify the expecting toc. Here is an example of powershell:

[
   {
      "toc_title":"Docs",
      "href":"/",
      "level":1,
      "children":[
         {
            "href":"/powershell/",
            "homepage":"/powershell/",
            "toc_title":"PowerShell Reference",
            "level":2,
            "children":[
               {
                  "href":"/powershell/azureps-cmdlets-docs/",
                  "homepage":"/powershell/azureps-cmdlets-docs/",
                  "toc_title":"Azure PowerShell",
                  "level":3
               }
            ]
         }
      ]
   }
]

Validate json file and push to github for OPS build to run.

Step 5: Validate content

Once the build completed validate if conceptual content and cmdlets are showing up for all the monikers that have been set up. If not, compare your docfx.json and .openpublishing.publish.config.json to other powershell repos.

Step 6: Enable version picker

This step can be done in parallel to validation of the content.

This is applicable ONLY IF there are multiple monikers i.e. versions. Create a user story and email Duncan Mckenzie to add version picker. Provide all the version URLs. Version picker doesn't automatically appear and requires some work from Duncan's team to manually add.

Eventually, this will be automated.

Step 7: Prepare redirections file

This step can be done in parellel to validation of content. Add redirections to master redirection file as needed and plan on scheduling work with operations team if any Akamai level redirections have to be done after going live.

Step 8 - Push to live

Once everything is validated and partner service team has signed off push to live.

Onboard a new version within existing service and existing docset

To onboard a new moniker version within existing service, first add the new version cmdlets to the repo according to the structure outlined in step 1.

Then follow instructions from above in:

  • Step 3 - Moniker set up
  • Step 4 - Update configurations - moniker mapping file, update docfx, no update required in .openpublishing.publish.config.json),
  • Step 5 - Validate content
  • Step 6 - Assuming the picker is already there then just contact Duncan with a user story to add the new version. Do the same if version picker is not available.
  • Step 7- Add Redirections as needed
  • Step 8 - Go live

Onboard a new service within existing docset

To onboard a new service, add the folder name in the repo and set up the folder structure as defined in step 1 of this topic.

Then follow instructions from above in: Step 3, Step 4 - you just need to add the moniker path within .openpublishing.publish.config.json, Step 5, Step 6, Step 7 and step 8.

  • Step 3 - Moniker set up
  • Step 4 - Update configurations
  • Step 5 - Validate content
  • Step 6 - Add version picker
  • Step 7 - Redirections as needed
  • Step 8 - Go live

For reference look at Azure Powershell repo where there are multiple services.