This RFC proposes to create a different version of the package documentation for installing and using individual packages.
Currently, the API docs are oriented around the main project and use nested import/require paths (e.g., @stdlib/math/base/special/sin. To facilitate individual package consumption, it would be nice if a user could toggle the docs and see specific instructions and examples for using individual packages (e.g., @stdlib/math-base-special-sin).
There are a couple of approaches which come to mind:
If a user has toggled to the individual package docs version, we could do README processing client-side, where we update import/require paths and add an install section after loading a README fragment from the server.
We could perform pre-processing where we generate individual package README fragments during the website build process. When a user loads individual package docs, we would fetch the individual package README fragment from the server and simply display as is to the user.
I think my preference would be the latter, if only because of SEO and less client-side load.
For preprocessing of READMEs, I think we are fairly close to being able to do this today. We just need to extract the logic found in the individual package publishing script into a separate package which we can independently consume.
Description
This RFC proposes to create a different version of the package documentation for installing and using individual packages.
Currently, the API docs are oriented around the main project and use nested import/require paths (e.g.,
@stdlib/math/base/special/sin
. To facilitate individual package consumption, it would be nice if a user could toggle the docs and see specific instructions and examples for using individual packages (e.g.,@stdlib/math-base-special-sin
).There are a couple of approaches which come to mind:
I think my preference would be the latter, if only because of SEO and less client-side load.
Related Issues
No.
Questions
No.
Other
No.
Checklist
RFC:
.