Fix namespace casing in API documentation
viktorveis opened this issue · 16 comments
API documentation uses lowercase namespaces. For example, https://docs.microsoft.com/en-us/qsharp/api/qsharp/microsoft.quantum.math.arccos includes this line:
Namespace:microsoft.quantum.math
Pasting it to a Q# program as is results in the following error:
error QS6104: No namespace with the name "microsoft.quantum.math" exists.
The actual namespace is Microsoft.Quantum.Math.
Please update documentation, so that it show correct namespace casing and allows pasting a namespace from documentation to code as is.
Thanks for raising this, it looks like this is a fairly severe regression. Oddly, the namespace is correctly formatted in the underlying YAML sources, such that I suspect this may be a regression on the OPS end.
Adding @KittyYeungQ and @geduardo for awareness.
Note that the "See also:" links also get broken by the lowercase change, but oddly it appears to happen at a different time than the namespace change @cgranade pointed out. E.g. for the AssertQubit operation, the Q# source file is exactly as it's always been, but the underlying YAML source for the API has the seeAlso term already changed to lowercase while the namespace is still properly formatted.
Could it be caused by the migration to DocFX3?
Could it be caused by the migration to DocFX3?
That's possible, yeah. It'd be surprising to me that the meaning of the schema used to generate doc HTML pages from YAML files changed that drastically between the two, but it would explain what we're seeing here.
As a side note, one possible path would be to take control of the Q# → API documentation pipeline by directly generating Markdown files from within the Q# compiler and runtime toolchain (microsoft/qsharp-runtime#253).
I've been doing some experiments here (#999) and going back to DocFX v2 makes the namespaces to look ok again (although some odd warnings appear). Anyways, this seems to confirm my suspicion: something changed in the migration to DocFX3 that caused this issue.
I've been doing some experiments here (#999) and going back to DocFX v2 makes the namespaces to look ok again (although some odd warnings appear). Anyways, this seems to confirm my suspicion: something changed in the migration to DocFX3 that caused this issue.
Well, crap, that isn't good. Thanks for confirming that; maybe it would be good, then, to accelerate work on microsoft/qsharp-runtime#253 so that we can phase out the YAML files that we don't control templates for.
Sure, I'd love to help with that but my C# skills are not good enough yet (I'm learning this summer tho!). We could try to go back to DocFX v2 until the Markdown generation tool is ready. Maybe we should check with the OPS team first.
Docs team identified the root cause: @Bradben is this something you could fix or may need help from @cgranade @efratshabtai @bettinaheim's team?
"We've noticed that the NameSpace's uid were declared with lower-case, referenced with upper-case. Since uid is case-sensitive, this result into xref-not-found and lower-cased uid got displayed in stead of name.
In docfx-v2, template holds the logic to fix this(turn upper-case to lower-case). But due to v3 xref behavior change, the fix won't work.
An easy approach would be changing the uid reference to lower-case, and the result will be correct. This approach also eliminate the hacky fix in template.
e.g. Microsoft.Quantum.Math => microsoft.quantum.math
more Details in AB#288357
v2: yml -> verify uid(uid-not-found v2 report) -> jint(uid lower cased) -> mustache -> resolve uid again(resolved)
v3: yml -> resolve uid(xref-not-found v3 report) -> jint -> mustache
uid declaration: microsoft.quantum.math
uid reference: Microsoft.Quantum.Math
the yml files were machine generated, and hence it would be great if this fix happens during generation.
### YamlMime:QSharpType
# This file is automatically generated.
# Please do not modify this file manually, or your changes may be lost when
# documentation is rebuilt.
uid: microsoft.quantum.math.arccos
name: ArcCos
type: function
namespace: Microsoft.Quantum.Math <= here need to be changed
NameSpace reference need to be lower-cased "Microsoft.Quantum.Math => microsoft.quantum.math"."
@KittyYeungQ, will that approach end up rendering the casing correctly in the documentation, e.g., as Microsoft.Quantum.Math?
@mingwli Can you comment on @rmshaffer 's question above?
### YamlMime:QSharpType
# This file is automatically generated.
# Please do not modify this file manually, or your changes may be lost when
# documentation is rebuilt.
uid: microsoft.quantum.math.arccos
name: ArcCos
type: function
namespace: Microsoft.Quantum.Math <= here need to be changed
NameSpace reference need to be lower-cased Microsoft.Quantum.Math => microsoft.quantum.math
Hi @mingwli would you mind helping us understand, so the namespace initials should never have been upper-cased in the yaml file or the live view? We intended to have live view have upper case. Is it no longer possible?
@KittyYeungQ The view will be Upper Case eventually.
It's a bit complicated to explain how it works.
The namespace is declared with uid microsoft.quantum.math.
And once declared, this uid can be used within this repo to reference the namespace e.g. namespace: Microsoft.Quantum.Math. And since the uid is case-sensitive, it requires the proper case(lower) to reference.
The final displayed text will be the namespace's Name property, which has the correct case.
I've created a branch to demo this #1030, sample built page
cc @herohua