Skip to content
This repository has been archived by the owner on Nov 16, 2023. It is now read-only.

Setup and workflow for Q# language topics from qsharp language repo

Jump to bottom
Bradben edited this page Oct 9, 2020 · 3 revisions

This page is to define the setup and workflow for syncing the Q# language files in the qsharp-language repo to the quantum-docs-pr repo for publishing as part of the QDK docset.

Syntax for the Markdown include statement is here.

Overall workflow:

  1. Source content is created in qsharp-language repo.
  2. For each source content file, a stubbed topic file is created in quantum-docs-pr that includes metadata, H1 heading, and an [!INCLUDE] statement linking the related source content file.
  3. At build, the source content is pulled from the qsharp-lang repo into the stubbed topic file and built as usual.

quantum-docs-pr changes

  • .openpublishing.publish.config.json is updated to include qsharp-language as a dependent repo.

QDK TOC structure

Current User Guide

  • Q# user guide
  • ...
  • Q# language
    • Program structure
      • ...
    • Statements
      • ...
    • Expression
      • ...
    • Type system
      • ...
  • TBD
    • Will the existing topic files under Q# language be replaced? (Types in Q# and Expressions)
    • Will other topic files under the Use Q# section be merged or replaced?
    • How do the Q# language topic files sync with the Language Ref topic files that Gillen is working on?

Stub files in quantum-docs-pr

Stub files will contain:

  • Standard metadata set (title, description, author, date, uid, etc.).
    • Suggestion for uid scheme: microsoft.quantum.qsharp.topic.
  • H1 heading. Source content referenced in an [!INCLUDE] statement can't include an H1 heading.
  • [!INCLUDE] statement with link to related source content file.

Example:

title: Conditional branching in Q#
description: Using the if statement in Q# for conditional branching.
...
uid: microsoft.quantum.qsharp.conditional-branching

(H1) Conditional branching

[!INCLUDE [source link] (~/includes/qsharp-language/Specifications/Language/2_Statements/ConditionalBranching.md)]

Source topic files

Links

Links in the source files should be an xref to the uid of the relative stub topic file. For example,

https://github.com/microsoft/qsharp-language/blob/main/Specifications/Language/2_Statements/ConditionalBranching

would be

xref:microsoft.quantum.qsharp.conditional-branching.

H1 headers

Included source files can't contain H1 headers. H1s will be part of the stub files.

Depending on how the qsharp-language repo is set up, PRs in that repo may get build warnings that there are no H1s in the files. These will have to be ignored.

Metadata

Included source files need to have a subset of metadata.

author: (github ID)
ms.author: (MS alias w/o domain)
ms.date: mm/dd/yyy
ms.prod: "quantum"
ms.topic: "include" (this triggers different validation rules, probably avoiding the H1 warning mentioned previously.)

The stub files will have a full set of metadata, duplicating the above (except ms.topic, which will be different).

Initial edit pass for setup

I can do a scrub of the current source files for:

  • Updating links to xrefs
  • Removing H1 headers
  • Adding metatdata
Clone this wiki locally