search

stdlib-js / www

Website for stdlib, a standard library for JavaScript and Node.js.
https://stdlib.io
Apache License 2.0
7 stars 8 forks source link

[RFC]: add "See Also" section to package READMEs #20

Closed kgryte closed 3 years ago

kgryte commented 3 years ago

Description

This RFC proposes adding a "See Also" section to package READMEs.

In order to get a list of related packages, we will need to extract this info from the namespace database, similar to how we populate repl.txt files during the REPL documentation build process.

Related Issues

No.

Questions

No.

Other

No.

Checklist

kgryte commented 3 years ago

One possibility for how this could look like would be

See Also

In short, the package name and a short description.

Planeshifter commented 3 years ago

Great idea!

I think we should include that section in the README.md files themselves such that it will also be visible when browsing the repos on GitHub or when looking at the npm packages. I have added a remark plugin that can be used to transform the README.md files accordingly: https://github.com/stdlib-js/stdlib/commit/2e8d2082aab5161ca62c98e4aeecfc752ed5b3ab.

It assumes that we will update the README.md files to include a new section:

<section class="related">

</section>

<!-- /.related -->

into which the "See Also" heading and list of package links will be inserted.

Planeshifter commented 3 years ago

See here for an example package with the new "See Also" section: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/zip

Planeshifter commented 3 years ago

And here is how it currently would look in the standalone packages: https://github.com/stdlib-js/utils-zip

kgryte commented 3 years ago

Re: main project. I don't think we want this in the main project GitHub repository for the same reason we don't do so for the repl.txt documents. Namely, additional churn and less value when used in the repository itself, rather than in generated documentation.

kgryte commented 3 years ago

For the standalone packages, we should uncapitalize the first character of the description (which is similar to namespaces, etc).

kgryte commented 3 years ago

Had a look through the plugin. The plugin looks good. I had just thought to simply append a section to the HTML fragments during build time, but, having the plugin allows more general usage, as you did for the standalone packages, which makes sense.

kgryte commented 3 years ago

I think I'd still prefer to leave the See Also section out of the READMEs in the main project repository. This section can be dynamically added during further processing (e.g., when generating standalone repos or when generating HTML fragments).

This does mean, however, based on how the plugin works, that we need to add a new empty <section class="related"></section> element to all package READMEs in the main project.

kgryte commented 3 years ago

Looking into a bit more, maybe you're right, we should just include the See Also section in the main project READMEs. Makes the tooling a bit easier downstream when, e.g., generating website documentation.

I think my concern stems from not wanting things to get out of sync, but, similar to REPL docs, etc, so long as we have the tooling (which we do thanks to your updating the make commands), this is something we can run pre-publish across the entire project.

Planeshifter commented 3 years ago

Yeah, I think we can automate this so that this section always stays to be up-to-date. I feel it's easier to just have that section present in all the different places. I think the main project repository is a common and legitimate entry point for people to browse the README.md files and seeing the related packages would be useful for all those who prefer that way of navigating through the library rather than going to the individual packages or the website documentation. Might also help us in keeping the related packages up-to-date and ensuring that they are relevant.

kgryte commented 3 years ago

I think that, in order to make this work from a tooling perspective, we'll need to run processing in parallel. remark is just too slow for individual README processing, especially here where we need to check every package in the project, and not just, e.g., the namespace READMEs, as for generating ToCs.

kgryte commented 3 years ago

These sections have now been added and are live on the API docs website.