RFC: Create documentation for REPL aliases

[Planeshifter]

Checklist

Please ensure the following tasks are completed before submitting a feature request.

• [x] Read and understood the Code of Conduct.
• [x] Searched for existing issues and pull requests.
• [x] The issue name begins with RFC:.

Description

Description of the feature request.

This RFC proposes to create a different version of the docs for the REPL usage of stdlib. Instead of the namespace-oriented (and thus tree-based) organization of the docs, the sidebar menu of the REPL docs could be organized along the objects the respective functions are attached to (identified by their alias). For each function, we could create special README.md documentation files tailored around interactive usage.

Related Issues

Does this feature request have any related issues?

No.

Questions

Any questions for reviewers?

Any comments on the implementation details provided below? Any problems which need to be resolved in order to proceed?

Other open question:

• The repl.txt files contain documentation for the parameters and return values of each function. Which of these (if any) should be included in the documentation? It seems to me that the return value description could be included at the beginning of the ##### Notes section?
• Where should the tooling live to turn a repl.txt file into a README.md for the website documentation?
• What other tooling do we need?

Other

Any other information relevant to this feature request? This may include screenshots, references, sample output, and/or implementation notes.

We need tooling for generating the documentation for the alias version of the functions. This could be based on the repl.txt files, which are already specifically tailored for describing how to use the respective functions int he REPL environment.

However, I would propose to merge parts from both the README.md and repl.txt files:

• We could keep the intro section from the README.md files, as it provides useful context for the function. In contrast to usage in a command line, where real estate is more limited, I do not see a disadvantage from keeping it for the docs on the website
• We would generate the usage section from the repl.txt docs. Specifically, we would need a script which performs the following steps:
  • take the function signature and add #### as a prefix to create heading.
  • take the first line of the description and insert under the signature heading.
  • take the examples for that signature and add a code block.
  • if a signature has options, add the following line: “The function accepts the following options :”
  • take the option fields and map to a Markdown list, along with the option descriptions
  • If a signature has an extended description, we’d add a ##### Notes section with each line in the extended description mapped to a Markdown list element.
• I propose not including the examples section from the main README.md files. Sometimes, the examples are rather long or include for-loops etc., which are not representative of REPL usage and might be rather cumbersome to execute.
• For packages that contain multiple exported functions (e.g. an additional factory method), we would need to have multiple signature headings inside the usage section.

[kgryte]

We could keep the intro section from the README.md files, as it provides useful context for the function. In contrast to usage in a command line, where real estate is more limited, I do not see a disadvantage from keeping it for the docs on the website

Agreed.

take the function signature and add #### as a prefix to create heading.

We'll need to ensure proper escaping. E.g., \[.

If a signature has an extended description, we’d add a ##### Notes section with each line in the extended description mapped to a Markdown list element.

Agreed. This makes sense, except it would not be each "line", but each "item", which may span multiple lines and include multiple sentences. Further, we'll have to account for "special" cases, where we've included lists (in which case, we need to generate a nested list) or used indentation to add an equation or something similar. Handling the extended description in a robust manner will be the trickiest aspect of README generation.

I propose not including the examples section from the main README.md files. Sometimes, the examples are rather long or include for-loops etc., which are not representative of REPL usage and might be rather cumbersome to execute.

Agreed. We should not copy over the Examples section from the main README files.

For packages that contain multiple exported functions (e.g. an additional factory method), we would need to have multiple signature headings inside the usage section.

Agreed.

The repl.txt files contain documentation for the parameters and return values of each function. Which of these (if any) should be included in the documentation? It seems to me that the return value description could be included at the beginning of the ##### Notes section?

Yeah, this could be tricky. When writing repl.txt files, I have often included extended comments regarding parameters and return values in the respective descriptions. We could...

# alias

<insert intro from README if present>

## Usage

#### alias( x, \[options,] y )

This is the main description.

``javascript
<insert code examples>
``

The function accepts the following parameters:

-   **x**: `<type>` this is the lowercased first letter description. If includes `Default:` then the value which follows should be surrounded by backticks.
-   **options**: `<Object>` function options description.
-   **options.foo**: `<number>` description for first option.
-   **options.bar**: `<string>` description for second option.
-   **y**: `<boolean>` parameter description.

The function returns:

-   **result**: `<Object>` this is the lowercased first letter return value description.
-   **result.beep**: `<number>` if the result value is an option with documented properties, then these would follow.

## Notes

-   First item of extended description (this may span multiple lines and sentences)
-   Second item of extended description (this may span multiple lines and sentences)

* * *

#### alias.factory( \[options] )

This is the main description.

``javascript
<insert example code>
``

The function accepts the following parameters:

<insert parameters>

The function returns:

<insert results>

## Notes

-    <insert items from extended description>

* * *

## References

<insert references if they are present>

* * *

## See Also

<insert related hyperlinked aliases>

Where should the tooling live to turn a repl.txt file into a README.md?

• https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/_tools/repl-txt

For example, @stdlib/_tools/repl-txt/to-markdown. This tool would take a repl.txt string and convert it to Markdown. The CLI would either read from stdin or accept a file name from which to read a repl.txt file.

Once this tool is written, we can add additional abstractions (i.e., tools) for converting multiple files or working with globs.

Questions

Lastly, we'll want to think about how we'll present aliases in the side menu, given that the namespace is flat and we don't have a natural means for grouping based on alias alone. One idea would be to keep the same top-level namespaces and on expansion show the aliases which originate from that namespace. For example, @stdlib/math/base/special/sin would map, in the side menu to

math
  |- base.sin
  |- base.tan

This would at least allow users to collapse categories. We could allow further segmentation with

math
  |- base
       |- sin
       |- tan
  |- sin
  |- tan

Hence, allowing base aliases under a particular category to be collapsed/expanded.

Thoughts?

[kgryte]

@Planeshifter Now that the website is updated, we could revisit this. 😃