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

Change the doc-generation function to produce a well known JSON definition file as the documentation artifact, instead of markdown. #142

Closed
Tracked by #564
iliapolo opened this issue Jun 29, 2021 · 5 comments
Closed
Tracked by #564

Change the doc-generation function to produce a well known JSON definition file as the documentation artifact, instead of markdown. #142

iliapolo opened this issue Jun 29, 2021 · 5 comments
Assignees
@Chriscbr
Labels
effort/medium About 3 days p2 risk/medium

Comments

@iliapolo
Copy link
Contributor

No description provided.

@addihorowitz addihorowitz mentioned this issue Jul 5, 2021
Open
@MrArnoldPalmer MrArnoldPalmer added effort/small About 1 day and removed effort/medium About 3 days labels Jul 6, 2021
@addihorowitz addihorowitz added p2 and removed p1 labels Jul 18, 2021
@github-actions
Copy link
Contributor

This issue is now marked as stale because it hasn't seen activity for a while. Add a comment or it will be closed soon.

@github-actions github-actions bot added the stale label Sep 17, 2021
@gabewomble
Copy link
Contributor

Not stale - currently lower priority

@github-actions github-actions bot removed the stale label Sep 18, 2021
@github-actions
Copy link
Contributor

This issue is now marked as stale because it hasn't seen activity for a while. Add a comment or it will be closed soon.

@github-actions github-actions bot added the stale label Nov 18, 2021
@Chriscbr Chriscbr removed the stale label Nov 18, 2021
@iliapolo
Copy link
Contributor Author

Not stale - currently lower priority

@MrArnoldPalmer MrArnoldPalmer mentioned this issue Nov 23, 2021
Closed
9 tasks
@Chriscbr Chriscbr assigned Chriscbr and unassigned MrArnoldPalmer Dec 29, 2021
@Chriscbr Chriscbr removed the effort/small About 1 day label Dec 29, 2021
@Chriscbr Chriscbr added the effort/medium About 3 days label Dec 29, 2021
This was referenced Dec 29, 2021
Closed
Merged
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
Copy link
Contributor

Resolved by #726

@Chriscbr Chriscbr mentioned this issue Jan 31, 2022
Merged
mergify bot pushed a commit to cdklabs/construct-hub-webapp 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
effort/medium About 3 days p2 risk/medium
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@iliapolo @Chriscbr @MrArnoldPalmer @gabewomble @addihorowitz