Feature - Autotoc generation

[saipramod]

This pull request introduces the ability to generate a Table of Contents (TOC) based on the underlying file system. The feature works as follows:

When auto TOC generation is enabled:

• Add auto: true to the toc.yml located alongside the docfx.json.
• This triggers the addition of items to the toc.yml in the order specified by the file system.
• The process is repeated recursively across all folders and subfolders, starting at the root of the project.
• If auto: false is encountered in any TOC, the auto TOC generation for that TOC will be halted.
• Auto TOC generation will check for the presence of an href before adding one, thus avoiding any duplicates.

[rwrife]

What naming conventions are you following for generating the human-readable names in the TOC? I assume you'd want to use something similar to what ADO Wiki follows or give the end-user options for detecting camel case, snake case, etc. Also, should there be an option to output toc.yml to the end user so they could use autotoc generation for the first pass, then easily switch to providing manually updated toc.yml files?

[rwrife]

Here are some rules I was following (in Powershell) to convert the folder name to human readable to handle these scenarios:

hello-world = Hello World
helloWorld = Hello World
MicrosoftAI = Microsoft AI

function Convert-HyphenToHumanReadable {
  param (
    [string]$InputString
  )

  # Replace hyphens (-) with spaces
  $readableName = $InputString -replace '-', ' '

  # Replace URL-encoded symbols using System.Uri to decode
  $decodedName = [System.Uri]::UnescapeDataString($readableName)

  return $decodedName
}

function Convert-CamelCaseToHumanReadable {
  param (
    [string]$InputString
  )

  # Step 1: Add space before capital letters, except for consecutive capitals
  $result = $InputString -creplace '(?<!^)(?<![A-Z\s_-])(?=[A-Z])', ' '

  # Step 2: Add space between a group of capitals and a lowercase letter
  $result = $result -creplace '(?<=[A-Z])(?=[A-Z][a-z])', ' '

  # Step 3: Special handling for words ending with 's' or 'S'
  $result = $result -creplace '\s([A-Z]+s)(?=$|\s)', '$1'

  # Step 4: Remove any extra spaces
  $result = $result -replace '\s+', ' '

  return $result.Trim()
}

[saipramod]

Here are some rules I was following (in Powershell) to convert the folder name to human readable to handle these scenarios:

hello-world = Hello World helloWorld = Hello World MicrosoftAI = Microsoft AI

function Convert-HyphenToHumanReadable {
  param (
    [string]$InputString
  )

  # Replace hyphens (-) with spaces
  $readableName = $InputString -replace '-', ' '

  # Replace URL-encoded symbols using System.Uri to decode
  $decodedName = [System.Uri]::UnescapeDataString($readableName)

  return $decodedName
}

function Convert-CamelCaseToHumanReadable {
  param (
    [string]$InputString
  )

  # Step 1: Add space before capital letters, except for consecutive capitals
  $result = $InputString -creplace '(?<!^)(?<![A-Z\s_-])(?=[A-Z])', ' '

  # Step 2: Add space between a group of capitals and a lowercase letter
  $result = $result -creplace '(?<=[A-Z])(?=[A-Z][a-z])', ' '

  # Step 3: Special handling for words ending with 's' or 'S'
  $result = $result -creplace '\s([A-Z]+s)(?=$|\s)', '$1'

  # Step 4: Remove any extra spaces
  $result = $result -replace '\s+', ' '

  return $result.Trim()
}

i see this an extension and not a part of the auto toc feature. so the auto toc does the job of generating toc using the underlying file system. you can apply an extension to massage those titles to fit whatever need. we can easily write one i think ryan. @yufeih can weigh in .

Found one, we already have a contribution for this.

massage-title-adowiki.zip

[saipramod]

@dotnet-policy-service agree company="Microsoft"

@dotnet-policy-service agree company="Microsoft"

[yufeih]

It makes sense to have a default naming convention for folders. Typically, folder names for URL segments uses either hyphens (-) or underscores (_) for spaces. We could follow the ADO wiki convention.

[yufeih]

auto should allow gen TOC based on the directory structure for any TOC file, not just the root

[saipramod]

i am glad i paused to ask this. what would be the scenario where if the root toc.yml is not present and the auto toc still need to populate the toc.yml in sub folders ? my understanding is if the root toc.yml is missing, there is no nav i.e there is no way for users to reach the toc unless they remember the url. Is my understanding off ?