electron/docs-parser

Parse Electron docs in a lossless way into a JSON file

📝 Available Translations: 🇨🇳 🇧🇷 🇪🇸 🇯🇵 🇷🇺 🇫🇷 🇺🇸 🇩🇪. View these docs in other languages on our Crowdin project.

The Electron framework lets you write cross-platform desktop applications using JavaScript, HTML and CSS. It is based on Node.js and Chromium and is used by the Visual Studio Code and many other apps.

Follow @electronjs on Twitter for important announcements.

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

Installation

To install prebuilt Electron binaries, use npm. The preferred method is to install Electron as a development dependency in your app:

npm install electron --save-dev

For more installation options and troubleshooting tips, see installation. For info on how to manage Electron versions in your apps, see Electron versioning.

Platform support

Each Electron release provides binaries for macOS, Windows, and Linux.

• macOS (Catalina and up): Electron provides 64-bit Intel and ARM binaries for macOS. Apple Silicon support was added in Electron 11.
• Windows (Windows 10 and up): Electron provides ia32 (x86), x64 (amd64), and arm64 binaries for Windows. Windows on ARM support was added in Electron 5.0.8. Support for Windows 7, 8 and 8.1 was removed in Electron 23, in line with Chromium's Windows deprecation policy.
• Linux: The prebuilt binaries of Electron are built on Ubuntu 20.04. They have also been verified to work on:
  • Ubuntu 18.04 and newer
  • Fedora 32 and newer
  • Debian 10 and newer

Quick start & Electron Fiddle

Use Electron Fiddle to build, run, and package small Electron experiments, to see code examples for all of Electron's APIs, and to try out different versions of Electron. It's designed to make the start of your journey with Electron easier.

Alternatively, clone and run the electron/electron-quick-start repository to see a minimal Electron app in action:

git clone https://github.com/electron/electron-quick-start
cd electron-quick-start
npm install
npm start

Resources for learning Electron

• electronjs.org/docs - All of Electron's documentation
• electron/fiddle - A tool to build, run, and package small Electron experiments
• electron/electron-quick-start - A very basic starter Electron app
• electronjs.org/community#boilerplates - Sample starter apps created by the community

Programmatic usage

Most people use Electron from the command line, but if you require electron inside your Node app (not your Electron app) it will return the file path to the binary. Use this to spawn Electron from Node scripts:

const electron = require('electron')
const proc = require('node:child_process')

// will print something similar to /Users/maf/.../Electron
console.log(electron)

// spawn Electron
const child = proc.spawn(electron)

Mirrors

• China

See the Advanced Installation Instructions to learn how to use a custom mirror.

Documentation translations

We crowdsource translations for our documentation via Crowdin. We currently accept translations for Chinese (Simplified), French, German, Japanese, Portuguese, Russian, and Spanish.

Contributing

If you are interested in reporting/fixing issues and contributing directly to the code base, please see CONTRIBUTING.md for more information on what we're looking for and how to get started.

Community

Info on reporting bugs, getting help, finding third-party tools and sample apps, and more can be found on the Community page.

License

MIT

When using Electron logos, make sure to follow OpenJS Foundation Trademark Policy.

docs-parser's Issues

Doesn't Handle String Union Types with Quotes inside Backticks

This is definitely a corner case, but currently prevents this example in the docs from being typed properly: https://github.com/electron/electron/blob/ce4ae584e357000b324228693ed7556922b6335f/docs/api/client-request.md?plain=1#L54-L58

I tried single quotes rather than double quotes with the same result, so the issue is quotes inside of the backticks. This might be tricky to make parse correctly with the current regex approach.

Is repoUrl Useful?

This comes out of #47. The repoUrl field in electron-api.json has been has broken URLs for a long time now and no one seems to have noticed. If no one is using the field, should it just be removed for simplicity? Leaving this as an open question since @ckerr brought it up on that PR review.

multi-mode Class description error

It seems that there is currently a bug when packageMode is multi that nullifies descriptions of each class into a rather excessively large string.

Specifically, it seems that it starts at the first description in the document and ends at the first constructor it encounters. If there are no constructors, it leaves it empty.

Here's an example (querystring and Worker Threads properties can be ignored): https://gist.github.com/bnb/bcc9394cfd81bd61ffdb9b3d303b799b

Parser not works anymore if useReadMe is disabled

Parser not works because it use wrong basedir for api lookup

  const apiDocsPath = options.baseDirectory || path.resolve('./', 'docs', 'api');
  const structuresPath = path.resolve(apiDocsPath, 'structures');

Leads to wrong api base Path.

{ [Error: ENOENT: no such file or directory, scandir 'electron-master/structures']
  errno: -4058,
  code: 'ENOENT',
  syscall: 'scandir',
  path:
   'electron-master/structures' }

commit: d8bec24

docs-parser/src/index.ts

Line 15 in d8bec24

const apiDocsPath = options.baseDirectory || path.resolve('./', 'docs', 'api');

Add usage guidelines and documentation

As it stands, the requisite formatting needed to make various parts of Electron's documentation type in specific ways remains tribal. Unless you work with Electron constantly, it's not intuitive or clearly laid out that, for example, one would need to say something like:

`MyDopeParam` String - Can be `a`, `b`, or `c`.

in order to have a string param type as a string literal. We should at the very least begin to incrementally centralize this knowledge to reduce friction for those who many want to contribute to our docs or otherwise work on the project.

It seems to be impossible to document functions that are attached to a certain property

I would like to fix this Issue.

Especially I would like to document the view.webContents.destroy() method so that I can use it from typescript without having to do shenangians like (view.webContents as any).destroy().

To make it work, normally all that would be required is the change from

    /**
     * A `WebContents` object owned by this view.
     *
     * @experimental
     */
    webContents: WebContents;

to

    /**
     * A `WebContents` object owned by this view.
     *
     * @experimental
     */
    webContents: WebContents & {
      /**
       * Destroys the `WebContents` of the associated `BrowserView`.
       *
       * @experimental
       */
      destroy(): void;
    };

in the typescript definition of the BrowserView class.

However because the typescript defintions are auto-generated form the JSON API file retrieved by parsing the documentation, it seems to me that it is impossible at the moment to make that improvement.

What would be the best option to make such edge cases work? Do we need to extend the parser and the defintions generator and then adjust the documentation somehow?

Doesn't Handle String Union Types with Double Quotes

Example from docs: https://github.com/electron/electron/blob/ce4ae584e357000b324228693ed7556922b6335f/docs/api/app.md?plain=1#L1137-L1141

process field not read correctly

This #14 never landed in electron project.
The electron-api.json is still released with process fields always true.

DX: include keyToken.content in error when keyToken.type is not `code_inline`

Currently, when the process crashes because it encounters an unexpected list entry (?) that is not an inline code block it spits out this message:

✖ Generating API in directory: "/Users/cyren/GitHub/node-docs-parser"
An error occurred while processing: "/Users/cyren/GitHub/node-docs-parser/docs/api/v8.md"
AssertionError: Expected key token to be an inline code block: expected 'text' to equal 'code_inline'

The last line is the useful context, and having dug more into the code I can now pretty clearly understand what the error is asserting. However, when running this as someone not experienced with the tool, having the context of "what text is actually triggering this to happen would be super useful.

I personally was able to figure out the exact context by adding console.log(keyToken) in the globally installed module and seeing the entry before it failed. I was able to see the specific content from keyToken.content which allowed me to debug my docs and solve the problem.

It would be awesome to see keyToken.content included in the error message if at all possible. One possible solution, though I don't know if it'll be properly output:

    expect(keyToken.type).to.equal('code_inline', `Expected key token to be an inline code block at "${keyToken.content}"`);`

[Bug]: [Electron.d.ts][gn-typescript-definitions][Invalid type annotations] Electron.PrintToPDFOptions > Margins

Preflight Checklist

• I have read the Contributing Guidelines for this project.
• I agree to follow the Code of Conduct that this project adheres to.
• I have searched the issue tracker for a bug report that matches the one I want to file, without success.

Electron Version

28.1.2

What operating system are you using?

Windows

Operating System Version

all

What arch are you using?

x64

Last Known Working Electron version

28.1.2

Expected Behavior

Electron.PrintToPDFOptions > Margins

web-contents.md, webview-tag.md file

#### `contents.print([options], [callback])`
### `<webview>.print([options])`
* `options` Object (optional)
  * `margins` Object (optional)
    * `marginType` string (optional) - Can be `default`, `none`, `printableArea`, or `custom`. If `custom` is chosen, you will also need to specify `top`, `bottom`, `left`, and `right`.
    * `top` number (optional) - The top margin of the printed web page, in pixels.
    * `bottom` number (optional) - The bottom margin of the printed web page, in pixels.
    * `left` number (optional) - The left margin of the printed web page, in pixels.
    * `right` number (optional) - The right margin of the printed web page, in pixels.

#### `contents.printToPDF(options)`
### `<webview>.printToPDF(options)`
* `options` Object
  * `marginsToPDF` Object (optional)
    * `top` number (optional) - Top margin in inches. Defaults to 1cm (~0.4 inches).
    * `bottom` number (optional) - Bottom margin in inches. Defaults to 1cm (~0.4 inches).
    * `left` number (optional) - Left margin in inches. Defaults to 1cm (~0.4 inches).
    * `right` number (optional) - Right margin in inches. Defaults to 1cm (~0.4 inches).

Actual Behavior

The docs are different, the gn-typescript-definitions script only creates one 'Margins'.

  interface WebContentsPrintOptions {
    ...
    margins?: Margins;
    ...
  }
  interface PrintToPDFOptions {
    ...
    margins?: Margins;
    ...
  }
  interface WebviewTagPrintOptions {
    ...
    margins?: Margins;
    ...
  }

  interface Margins {
    /**
     * Can be `default`, `none`, `printableArea`, or `custom`. If `custom` is chosen,
     * you will also need to specify `top`, `bottom`, `left`, and `right`.
     */
    marginType?: ('default' | 'none' | 'printableArea' | 'custom');
    /**
     * The top margin of the printed web page, in pixels.
     */
    top?: number;
    /**
     * The bottom margin of the printed web page, in pixels.
     */
    bottom?: number;
    /**
     * The left margin of the printed web page, in pixels.
     */
    left?: number;
    /**
     * The right margin of the printed web page, in pixels.
     */
    right?: number;
  }

Testcase Gist URL

No response

Additional Information

No response

Bullet lists incorrectly take precedence over explicit `Returns <type>`

See electron/electron#37781 - this lead to a wildly incorrect return type of:

getPreferredSystemLanguages(): Array<'app.getLocale()' | 'app.getSystemLocale()' | 'app.getPreferredSystemLanguages()' | 'app.getLocale()' | 'app.getSystemLocale()' | 'app.getPreferredSystemLanguages()'>;

Array type and optional information missing for optional array type parameters

Example:

• app.setAsDefaultProtocolClient(protocol[, path, args]) for the args parameter it shows String instead of String[] and no (optional) label.

Other occurences can be found by searching for [] (optional) in the folder docs/ inside the "electron" repository.

Bad Typing of Return Type with Union

There's been some cases in the docs where return types are listed as Returns `<foo>` | `<bar>` which gets turned into a return type of just <foo>, and | `<foo>` gets added to the description. Can be fixed in the docs by typing as Returns `<foo> | <bar>` instead (which is how most return type unions are written in the docs), but we should either handle the case here or detect it and throw an error.

Example:

#### `ses.getExtension(extensionId)`

* `extensionId` string - ID of extension to query

Returns `Extension` | `null` - The loaded extension with the given ID.

**Note:** This API cannot be called before the `ready` event of the `app` module
is emitted.

Gets typed as:

/**
 * | `null` - The loaded extension with the given ID.
 *
 * **Note:** This API cannot be called before the `ready` event of the `app` module
 * is emitted.
 */
getExtension(extensionId: string): Extension;

process field not read correctly

process fields are not read correctly, currently always true.

docs-parser/src/DocsParser.ts

Lines 164 to 168 in d4d62e1

	// FIXME: We should read the process correctly
	process: {
	main: true,
	renderer: true,
	},

Agnostic interest: Collection of the static, electron-specific bits of docs-parser

Currently running through docs-parser to see if it could be adapted to something like Node.js's docs. Here's a set of things that I've found to be highly electron-focused:

• Output file is by default called electron-api.json.
  • Possible resolution: default to api.json and provide a CLI flag to change the name to something custom (like electron-api.json or node-api.json).
• Website URL is hardcoded to electronjs.org
  • Possible resolution: have a project config that can define this.
  • Possible resolution: don't include unless CLI flag is passed or a project config exists.
• Repo URL is hardcoded to electron/electron
  • Possible resolution: have a project config that can define this.
  • Possible resolution: don't include unless CLI flag is passed or a project config exists.
• Process property exists in the root of the JSON output where it may not be useful for anything outside of Electron.
  • Possible resolution: opt-in to including this via flag/config.

Doesn't Handle String Union Types With Numbers or Punctuation

Can't handle the following cases:

• Numbers and periods: https://github.com/electron/electron/blob/2a16c73834358f85ef20c07e50dfb5178c30bb1e/docs/api/session.md?plain=1#L1210C60-L1214
• Colons: https://github.com/electron/electron/blob/2a16c73834358f85ef20c07e50dfb5178c30bb1e/docs/api/client-request.md?plain=1#L41-L42