[RFC]: add API documentation index page

stdlib-js / www

Website for stdlib, a standard library for JavaScript and Node.js.

https://stdlib.io

Apache License 2.0

6 stars 8 forks source link

[RFC]: add API documentation index page #23

Open kgryte opened 2 years ago

kgryte commented 2 years ago

Description

This RFC proposes adding an API documentation index page (e.g., see NumPy).

This would provide a single page which links to all the package docs. This would be useful both to provide a high level overview of symbols in the namespace and for crawling.

Related Issues

No.

Questions

No.

Other

No.

Checklist

[X] I have read and understood the Code of Conduct.
[X] Searched for existing issues and pull requests.
[X] The issue name begins with RFC:.

kgryte commented 2 years ago

One question is how this index should be organized. By namespace? Alphabetically according to path basename (e.g., @stdlib/math/base/special/sin => sin)? Do we replicate the tree structure? Do we list all packages as just a single flat list?

kgryte commented 2 years ago

I think replicating the tree structure should be fine. We can, however, be more economical with space by arranging tree leaves across, say, 4 columns. For example,

A

  array

    base

      bar      foo1    foo4   foo7
      beep     foo2    foo5   foo8
      boop     foo3    foo6   foo9

    contains
    ...

There might be some tricky issues with layout (namely, indentation). Could also limit tree depth and use . syntax (e.g., base.special.sin), which may also be fine.

kgryte commented 4 months ago

An example of a nicely organized index page is D3: https://d3js.org/api.