Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve API Reference direct URLs #714

Closed
RomainMuller opened this issue Nov 19, 2021 · 1 comment · Fixed by #890
Closed

Improve API Reference direct URLs #714

RomainMuller opened this issue Nov 19, 2021 · 1 comment · Fixed by #890
Assignees
@Chriscbr
Labels
bug Something isn't working priority/p1

Comments

@RomainMuller
Copy link
Contributor

We should improve the URLs for API Reference entry points so that they are more reliable & less prone to collisions. The list of problems with those follows:

  • They are based on the language-specific fully qualified name, so one cannot change languages once on those pages (as the name is not valid in other languages). The original Jsii FQN should be used instead.
  • They are heavily sanitized (any non-alphanumerical character is removed, and it is fully down-cased), so they are ripe for collisions. The original FQN (made assembly-relative, so for example @aws-cdk/core.Construct would be Construct) can be used as-is in the URL. It'll also make URLs more readable, and easier to "manually write"

This requires coordinated changes in jsii-docgen (which provides data to the front-end through the markdown document), construct-hub (which passes a linkFormatter to jsii-docgen), and construct-hub-webapp (which has to route those URLs to the right content, and also generates these URLs again in the Nav-Tree).
@RomainMuller RomainMuller added bug Something isn't working priority/p1 labels Nov 19, 2021
@RomainMuller RomainMuller mentioned this issue Nov 19, 2021
Closed
@Chriscbr Chriscbr mentioned this issue Dec 24, 2021
Merged
@Chriscbr
Copy link
Contributor

Since this requires breaking changes across multiple packages, I'm planning to address this as part of cdklabs/construct-hub#142

mergify bot pushed a commit to cdklabs/jsii-docgen that referenced this issue Jan 18, 2022
@Chriscbr
feat!: JSON doc generation (#533)
757aa06 
Supersedes #481
Part of cdklabs/construct-hub-webapp#714 and cdklabs/construct-hub#142

Allows rendering language specific documentation to a JSON object in addition to a markdown string. This allows the consumer more flexibility to render the structure of the API reference as needed without regenerating markdown documents.

This PR builds upon #481 by cleaning up the JSON schema (in `schema.ts`) and also changing the markdown rendering logic to be based on the JSON output -- so the markdown rendering does not depend on any `TranspiledXxx` classes or interfaces.

All headers now have anchor tags which default to the unique language-agnostic FQNs (e.g. `@aws-cdk/aws-s3.Bucket.parameter.scope`). Based on my research, all characters used in JSII FQNs (A-Za-z0-9_-/.@) are allowed as URL fragments, and are also allowed as id's in HTML5, so this is a reasonable default.

This PR also extends the notion of fully qualified names to all "entities" in the document (methods, properties, enum members, and even method parameters) denoted by the "id" fields within the JSON schema, so that any section of a document can be uniquely linked - not just types.  The `JsiiEntity` interface in `schema.ts` is intended to encapsulate any information that should be needed to render a link, including the package version it's from (this is necessary for Construct Hub to be able to link to the correct versions of packages).

Markdown generation can now be customized using three hooks:

- `anchorFormatter: (type: JsiiEntity) => string` - customize the IDs given to anchors tags that are placed next to every header in the document, so that any part of the API reference can be directly linked
- `linkFormatter: (type: JsiiEntity, metadata: AssemblyMetadataSchema) => string` - customize how links should be rendered when they appear in tables, descriptions, etc. -- e.g. to include logic to "link to another page"
- `typeFormatter?: (type: TypeSchema, linkFormatter) => string` - customize how composite types should be rendered when they include nested types - this allows functionality like the screenshot below:

<img width="912" alt="Screen Shot 2021-12-23 at 7 34 14 PM" src="https://user-images.githubusercontent.com/5008987/147302108-d8575415-f235-4ea8-91cb-db570f86274a.png">

See `markdown.test.ts` for an example of how the markdown rendering hooks would be used to format links for Construct Hub.

Examples:

@aws-cdk/aws-ecr Python API.json: https://gist.github.com/Chriscbr/731b315808faaf2a2161d686ce248368
@aws-cdk/aws-ecr Python API.md: https://gist.github.com/Chriscbr/d0833a9ecce258dead648a63253b8b0e

BREAKING CHANGE: `Documentation.render` is now named `Documentation.toMarkdown`. In addition, the options parameter for this method has changed. `TranspiledType` is no longer exported.
@Chriscbr Chriscbr mentioned this issue Jan 31, 2022
Merged
@mergify mergify bot closed this as completed in #890 Jan 31, 2022
mergify bot pushed a commit that referenced this issue Jan 31, 2022
@Chriscbr
fix: API reference resets when switching languages (#890)
3ace71e 
Reverts the changes from #723 since the Construct Hub backend now generates IDs / urls that are stable across languages when applicable (cdklabs/construct-hub#142). More precisely, when a linked section of a page has docs in multiple languages, the corresponding directory and URL hash should be the same across them (`/api/Foo#bar`).

Fixes #714
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@Chriscbr Chriscbr

Labels
bug Something isn't working priority/p1
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

fix: API reference resets when switching languages cdklabs/construct-hub-webapp
2 participants
@RomainMuller @Chriscbr