{"id":17295732,"url":"https://github.com/bnb/node-docs-parser","last_synced_at":"2025-04-13T03:27:47.560Z","repository":{"id":74933493,"uuid":"225205224","full_name":"bnb/node-docs-parser","owner":"bnb","description":"A proof of concept for using Electron's docs-parser tool to rewrite the Node.js documentation.","archived":false,"fork":false,"pushed_at":"2020-02-24T19:59:45.000Z","size":68,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-04T22:02:24.927Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bnb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-01T18:05:31.000Z","updated_at":"2024-09-14T21:04:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"ed76810e-5ddc-4eb3-9f88-41df863d32d4","html_url":"https://github.com/bnb/node-docs-parser","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnb%2Fnode-docs-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnb%2Fnode-docs-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnb%2Fnode-docs-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnb%2Fnode-docs-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bnb","download_url":"https://codeload.github.com/bnb/node-docs-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248659154,"owners_count":21141083,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-15T11:11:04.480Z","updated_at":"2025-04-13T03:27:47.538Z","avatar_url":"https://github.com/bnb.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# node-docs-parser\n\nThis is a repo to test the viability of the possibility of suggesting to the Node.js project that we migrate to the [electron/docs-parser](https://github.com/electron/docs-parser) for our documentation rather than continuing with our existing tooling.\n\n## Usage\n\nYou will need to clone this repo and install `@electron/docs-parser` globally:\n\n```sh\ngit clone git@github.com:bnb/node-docs-parser.git\nnpm i -g @electron/docs-parser\n```\n\nyou'll also need to create an (empty) `strucutres` directory in `docs/api/` (just because I've not committed any files to it):\n\n```sh\nmkdir docs/api/structures\n```\n\nnext, you'll need to navigate to the direcory and then run the CLI:\n\n```sh\ncd node-docs-parser\nnpm run parse # this will build the docs!\n```\n\n## Repository Structure\n\n- `/docs/api/`\n  - where the API docs live. `electron-docs-parser`looks here by default.\n- `/docs/api/structures/`\n  - required to exist by `electron-docs-parser`. Not currently in use but maybe probably should be?\n- `/originals/`\n  - original sources from the Node.js repo for docs in `/docs/api/`\n- `/electron-api.json`\n  - JSON output. Currently somehwat Electron specfici due to hard-coded-ness of the `@electron/docs-parser` tool, but there's currently a PR open to make this more dynamic ([electron/docs-parser#21](https://github.com/electron/docs-parser/pull/21)).\n\n## Current Blockers\n\n- Several parts of the docs-parser tooling are highly electron-specific [electron/docs-parser#19](https://github.com/electron/docs-parser/issues/19)\n- Moving as-is, Node.js would _seemingly_ lose the ability to include meta information (`introduced`, `stability`, and `history`)\n  - Having discussed this with Sam from Electron, there are ways we'd be able to address this.\n- Currently a bug in which multi-mode outputs incorrect descriptions for additional instances of `Class` in the JSON output. [electron/docs-parser#17](https://github.com/electron/docs-parser/issues/27)\n\n## Lessons Learned\n\n- Converting `querystring` was relatively straightforward. Effectively just converting the default Node.js format to the docs-parser format.\n- Converting `v8` was significantly more complex. Certain narrative elements of the Node.js docs – or, at least, the `v8.md` doc - are fundamentally incompatible with the Electron docs and need to either be re-integrated or dropped entirely.\n  - This isn't necessarily a positive nor a negative - more of a neutral observation. It could be argued that removing certain kinds of one-off narrative elements could bring better overall consistency to the docs, which could be an overall win.\n  - A more specific example is the `Serialization API` section of v8.md in the Node.js docs. This section is a narrative seperation that sets apart an API when it should quite likely be sitting at the same level as the rest of the APIs available from the module. The `Serialization API` heading and commentary was axed, moving the commentary into the actual Class definitions themselves. This was necessary because docs-parser expects certain elements (like `Instance Methods`) to be at certain levels of heading.\n- Converting `worker-threads`, I realized how inconsistent several elements of Node.js documentation writing is and how docs-parser forces us into a more consistent folow.\n  - Reading the docs prior to docs-parser, it feels like each bit was writen independently of every other bit, leaving me with a disjointed taste. Using docs-parser, everything becomes uniform and much smoother across sections.\n  - Despite being even more complex than `v8`, this one actually felt significantly more understandable at the end given the restrictions around `Instance Methods`, `Instance Properties`, and `Instance Events` that lead to less jittery interactions while reading through the documentation and a more consistent and modular narrative structure.\n  - Enforces a gramatical distinction between methods that `Return` and properties that are `a`/`an` _something_. While very minor, as a reader this feels very logical and is a helpful distinction.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbnb%2Fnode-docs-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbnb%2Fnode-docs-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbnb%2Fnode-docs-parser/lists"}