Add JSDoc site to api.drupal.org

Created on 5 June 2015, over 9 years ago
Updated 14 May 2024, 8 months ago

Problem/Motivation

On #25901: Parse/save/display JavaScript files β†’ , we've been discussing integrating JavaScript parsing into the API module. nod_ (the Drupal Core JS maintainer) and I agree that it would be fine (and definitely easier, and maybe better anyway) to just have a separate area, say api.drupal.org/js, that would host a JSDoc site that would parse the Drupal Core JavaScript and display it. This issue is about setting that up.

Also, note that on #2182153: [Meta] Document Drupal JavaScript using JSDoc β†’ , we're fixing up the JS code so it can be parsed with JSDoc, which is the industry-standard way to document/parse/display JS documentation reference sites.

Proposed resolution

1. Create api.drupal.org/js (or js.drupalcode.org), which would use JSDoc to parse the Drupal Core JavaScript files, and display them in a reference site.

2. Theme the JSDoc site consistent with *.drupal.org. (To be handled in a child issue)

3. Add navigation to the JSDoc and PHP doc sites linking to each other. (To be handled in a child issue)

4. Enjoy. ;)

Remaining tasks

1. Install prerequisites for generating jsDoc (node 4+, jsDoc)
To install jsDoc:
npm install -g jsdoc

2. Setup CI (Jenkins?) to parse Drupal codebase using _nod's config found here https://gist.github.com/theodoreb/56fb7170c89f0779548a
Config File

Generating command:
jsdoc --verbose -r --template jaguarjs-jsdoc --configure baseline-config.json

3. Put static site that is generated in a webroot to be served under js.drupalcode.org (the static site should be output in the "out" directory)

4. Add child issues to theme js site and add links to and from api.drupal.org

User interface changes

New JSDoc site.

API changes

None.

πŸ“Œ Task
Status

Closed: outdated

Version

1.0

Component

User interface

Created by

πŸ‡ΊπŸ‡ΈUnited States jhodgdon Spokane, WA, USA

Live updates comments and jobs are added and updated live.
  • Needs issue summary update

    Issue summaries save everyone time if they are kept up-to-date. See Update issue summary task instructions.

Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • πŸ‡ͺπŸ‡ΈSpain fjgarlin

    All this conversation really feels like there is a need for a new module, maybe called "jsdoc" or something like that. Even if it might do the same as the "API" module for PHP modules, it definitely would do it with a whole different set of libraries, tools, etc, which no overlap with the "API" module in my opinion.

    If we were to have this module, then it could be integrated in "api.drupal.org" as another module:
    - "API" module for PHP files. All paths here start with "api/...".
    - "jsdoc" for JS files. All paths here could start with "js/..." or "jsdoc/..." or whatever is best.

    Then, via Drupal, we could easily add blocks to "connect" the two parts.
    But all of this, without having a full-on Drupal module for JS parsing, feels like it's totally out of scope as it's not a quick task. We'd need to see how the new module would behave with several Drupal versions, what's the performance of it, etc.

    Given that there was not much activity in a few years, I'm going to mark this as outdated. Creating a "jsdoc" module would be amazing and then we could look into integrating it, but not before that in my opinion.

Production build 0.71.5 2024