Page MenuHomePhabricator

[SPIKE] Document types and constants on the Codex docs site
Closed, ResolvedPublic3 Estimated Story Points

Description

Background

The generated props data for components sometimes lists a prop type of a TypeScript type name, without any information about what that type is. The same goes for constants, e.g. when they're used as the default value of a prop. We need to provide users a way to see this information on the demo site (or, at least, link to the proper place in the code); otherwise they must either have type hinting set up in their IDE (which may only be possible within a TypeScript project) or look at the Codex code to see what the type means.

For example, this is what the menuItems prop for the Lookup component looks like on the docs site:

image.png (184×1 px, 33 KB)

The reader will have no way of accessing information about the MenuItemData type from here.

Potential solutions

Ideally, we would automate one of the following:

  • Turn types into a link that goes to either an individual page on the docs site about that type, or a single page that lists all the types (and one for constants)
  • Display the type definition on the demo page somehow (print it out below the type name, show it on hover, etc)

A quicker but less elegant solution would be to link to the types or constants file on gtiles or something from the usage docs if a constant or TypeScript type is used.


Acceptance criteria
  • Design a way to provide type and constant definitions to the user from demo pages
  • Implement it

Event Timeline

AnneT renamed this task from Document types and constants on the demo site to Document types and constants on the Codex docs site.Jul 28 2022, 8:42 PM
ldelench_wmf subscribed.

Upping priority to "high" per @AnneT 's comment T314082#8113536 and pushing back to "up next" since it's not assigned. Feel free to adjust!

Where should information about types and constants live in the Codex docs?

Does our build system support @link tags inside of documentation ?

We may need to refine this task or do a spike to figure out what is possible.

ldelench_wmf set the point value for this task to 3.Sep 19 2022, 3:33 PM
Restricted Application changed the subtype of this task from "Task" to "Spike". · View Herald TranscriptSep 19 2022, 4:52 PM
ldelench_wmf renamed this task from Document types and constants on the Codex docs site to [SPIKE] Document types and constants on the Codex docs site.Sep 19 2022, 4:52 PM
AnneT changed the task status from Open to In Progress.Sep 22 2022, 7:54 PM

Change 834375 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] [Proof of concept] Generate types page

https://gerrit.wikimedia.org/r/834375

As noted in the PoC patch, we could use typedoc to get a description of all the types in JSON, but we'll need to do quite a bit of work to output a proper page with all the types and their associated information.

I suggest we forgo this for now and just manually create a page of types. We can try to pick the PoC patch back up later if we have time.

Change 835258 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] docs: Document types and constants

https://gerrit.wikimedia.org/r/835258

egardner changed the subtype of this task from "Spike" to "Task".Sep 28 2022, 9:05 PM
egardner updated the task description. (Show Details)

We've moved beyond spike and are in the process of implementing a solution (writing code that generates the appropriate documentation in the docs site).

Change 835258 merged by jenkins-bot:

[design/codex@main] docs: Document types and constants

https://gerrit.wikimedia.org/r/835258

Closing this task as complete; this only impacts technical documentation so there is no need for QA, design review, or release sign-off.

Change 849191 had a related patch set uploaded (by VolkerE; author: VolkerE):

[mediawiki/core@master] Update Codex from v0.2.1 to v0.2.2

https://gerrit.wikimedia.org/r/849191

Change 849191 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.2.1 to v0.2.2

https://gerrit.wikimedia.org/r/849191

Change 834375 abandoned by Anne Tomasevich:

[design/codex@main] [Proof of concept] Generate types page

Reason:

https://gerrit.wikimedia.org/r/834375