search

stdlib-js / google-summer-of-code

Google Summer of Code resources.
https://github.com/stdlib-js/stdlib
23 stars 5 forks source link

[Idea]: generate web documentation from JSDoc comments #19

Open kgryte opened 1 year ago

kgryte commented 1 year ago

Idea

stdlib relies heavily on JSDoc comments to document its source code. Currently, the project has only rudimentary support for generating HTML docs from those comments. The goal of this idea would be to

  1. Write an in-house JSDoc parser.
  2. Generate HTML documentation from the parsed comments which is capable of supporting project conventions and its embrace of radical modularity.

JSDoc comments are oriented toward JavaScript source files; however, stdlib also uses similar documentation practices for documenting C source files and make files. A possible extension to the in-house JSDoc parser would be to support these other source file types. As those file types may require separate AST parsers, supporting other file types is likely to require writing separate comment parsers for each source type.

Expected Outcomes

In addition to the current API documentation, a user will be able to navigate to a package's JSDoc documentation to gain more insight into supported input and output dtypes and implemented algorithms. This would be especially useful for rendering the extended JSDoc comment of elementary mathematical functions.

Involved Software

No other software is necessary.

Prerequisite Knowledge

JavaScript, Node.js, HTML/CSS.

Difficulty

Intermediate.

Project Length

350 hours. The length can likely be scaled down; however, there are several unknowns, and it may not be straightforward to develop an in-house parser which caters to the unique structure and setup of stdlib. For advanced contributors, possibility to explore support for source file types other than JavaScript (e.g., C and make).

Potential Mentors

@kgryte @Planeshifter @steff456

kgryte commented 3 months ago

Some relevant project resources:

kgryte commented 3 months ago

While the focus of the OP is centered around the main project repository, ideally whatever is done can also apply and be used for generating JSDoc documentation in standalone stdlib repositories for individual packages.

kgryte commented 3 months ago

Note that the generation of HTML generation would likely entail the creation of a web frontend, with support for theming and integration with the main project documentation. Generated JSDoc documentation is likely to be static, but one can envision possible extension to supporting inter-package linking (e.g., require statements would be transformed into links).