docs(react-docgen-typescript-loader): add proof-of-concept Axis doc page #681
Conversation
| @@ -38,12 +37,6 @@ | |||
| "prepare-release": "git checkout master && git pull --rebase origin master && yarn run docs && lerna updated", | |||
| "release": "yarn run prepare-release && lerna publish --exact" | |||
| }, | |||
| "lint-staged": { | |||
There was a problem hiding this comment.
this was becoming annoying/very slow 🐌
| "marked": "^0.7.0", | ||
| "raf": "^3.4.0", | ||
| "react": "^15.0.0-0 || ^16.0.0-0", | ||
| "react-docgen": "^2.21.0", | ||
| "react-docgen": "^5.3.0", |
There was a problem hiding this comment.
I think we can remove this once all packages are converted
| .title > :not(:last-child) { | ||
| margin-right: 12px; | ||
| } | ||
| .description > :global(p) { |
There was a problem hiding this comment.
:global is needed because styled-jsx can't figure out that Markdown creates a p so the style doesn't apply
| } | ||
| @media (max-width: 600px) { | ||
| .doc-container { | ||
| flex-direction: column-reverse; |
There was a problem hiding this comment.
this mostly mirrors the current layout/responsive behavior. noting that sticky is broken in the current docs/I couldn't get it to work here either so removed it
| @@ -3,7 +3,7 @@ import React from 'react'; | |||
| export default () => ( | |||
| <div className="footer"> | |||
| <div> | |||
| <img src="static/favicon.ico" alt="vx" /> | |||
| <img src="/static/favicon.ico" alt="vx" /> | |||
There was a problem hiding this comment.
all of these 'static => /static changes are needed for correct URLs within the nested next pages like pages/docs/Axis
| import React from 'react'; | ||
| import { VxPackage } from '../types'; | ||
|
|
||
| export default function PackageList({ |
There was a problem hiding this comment.
tried to use the same component for /docs and for the package side nav on the /docs/axis page
| {!compact && <p>Annotate elements of a chart</p>} | ||
| </li> | ||
| <li> | ||
| <a href="/docs/axis" className={emphasizePackage === 'axis' && 'emphasize'}> |
There was a problem hiding this comment.
noting the only one that goes to a new /docs page versus .html
| </li> | ||
| </ul> | ||
|
|
||
| <ApiTable anchorId="Axis" docgenInfo={Axis.__docgenInfo} /> |
There was a problem hiding this comment.
gotta @ts-ignore these, not sure there's a clean way to avoid that 🤔
also noting that we'll have to do this for each component we want to annotate, but I think that's okay, it's not a lot of work
williaster
force-pushed
the
chris--fix-docgen
branch
from
e4ea82a
to
163ae5a
Compare
docs(vx-drag): update to docgen
docs(vx-event): convert to docgen
docs(vx-geo): convert to docgen
docs(vx-glyph): update to codegen
docs(vx-gradient): update to docgen
docs(vx-grid): update to docgen
docs(vx-group, vx-point): update to docgen
docs(vx-heatmap): convert to docgen
docs(vx-hierarchy, vx-scale): convert to docgen
docs(vx-legend): update to docgen
docs(vx-marker, vx-network): update to docgen
docs(vx-mock-data): update to docgen
docs(vx-pattern, vx-responsive): convert to docgen
docs(vx-shape): convert to docgen
docs(vx-text, vx-tooltip) convert to docgen
docs(vx-threshold): convert to docgen
docs(vx-voronoi): convert to docgen
docs(vx-zoom, vx-vx): convert to docgen
docs(vx-stats): convert to docgen
📝 Documentation
This PR is the first of several to address #680, to fix auto-generation of package documentation to include our
TypeScriptannotations, and make the process more efficient. In this PR I've made several updates and created a proof-of-concept for theAxisdocs. In subsequent PRs we can update the docs for other packages.For documentation/others, the current flow for auto-doc generation is as follows:
docscript is invoked, which runs abashnodescript that reads in the files for the package and generates anapi.mdfilepackage/docs/*, theapi.mdfile is concatenated withdescription.mdandinstall.mdfiles to createdocs.mddocs.mdis used to create a static.htmlpage that is rendered by thenext jsapp under e.g.,/static/docs/vx-responsive.htmlThis is decently complex/lots of pieces, requires a lot of manual check-in work which means docs can become stale, and the script has been broken since the
tsrewrite. In this PR I update all of this to be in thenext jsapp asreactcomponents.Specifically this PR makes the following changes:
nextwebpackconfig to include thereact-docgen-typescript-loaderwhich annotates components with any defined typesApiTableto render prop types + descriptions + default values (mirroring the oldapi.md)DocPagecomponent to render the docs for a given package/docspage tovxecosystem more understandablepages/docs/Axispage usingDocPageApiTable.htmllinks in/docsto point to this new doc pagedocsscript, and oldvx-axis/docs/*.mdfilesOverall the result is similar to before, but hopefully will be more manageable. If you have design feedback, or suggestions for package categorization labels lmk 🙏
Before
After
@hshoff @kristw