Merge pull request #11178 from electron/fenced-code-block-lang
enforce rules on code blocks style in docs
This commit is contained in:
commit
70643a865b
20 changed files with 91 additions and 69 deletions
6
.remarkrc
Normal file
6
.remarkrc
Normal file
|
@ -0,0 +1,6 @@
|
|||
{
|
||||
"plugins": [
|
||||
["remark-lint-code-block-style", "fenced"],
|
||||
["remark-lint-fenced-code-flag"]
|
||||
]
|
||||
}
|
|
@ -112,7 +112,7 @@ A comma-separated list of servers for which integrated authentication is enabled
|
|||
|
||||
For example:
|
||||
|
||||
```
|
||||
```bash
|
||||
--auth-server-whitelist='*example.com, *foobar.com, *baz'
|
||||
```
|
||||
|
||||
|
|
|
@ -314,7 +314,7 @@ Template:
|
|||
|
||||
Menu:
|
||||
|
||||
```
|
||||
```sh
|
||||
- 1
|
||||
- 2
|
||||
- 3
|
||||
|
@ -337,7 +337,7 @@ Template:
|
|||
|
||||
Menu:
|
||||
|
||||
```
|
||||
```sh
|
||||
- ---
|
||||
- a
|
||||
- b
|
||||
|
|
|
@ -146,7 +146,7 @@ of the main process.
|
|||
|
||||
e.g.
|
||||
|
||||
```
|
||||
```sh
|
||||
project/
|
||||
├── main
|
||||
│ ├── foo.js
|
||||
|
|
|
@ -78,7 +78,7 @@ Note that it is not enough to call
|
|||
code runs after it is possible to make changes to chromium sandbox settings. The
|
||||
switch must be passed to electron on the command-line:
|
||||
|
||||
```
|
||||
```sh
|
||||
electron --enable-sandbox app.js
|
||||
```
|
||||
|
||||
|
@ -151,10 +151,12 @@ Important things to notice in the preload script:
|
|||
To create a browserify bundle and use it as a preload script, something like
|
||||
the following should be used:
|
||||
|
||||
browserify preload/index.js \
|
||||
-x electron \
|
||||
-x fs \
|
||||
--insert-global-vars=__filename,__dirname -o preload.js
|
||||
```sh
|
||||
browserify preload/index.js \
|
||||
-x electron \
|
||||
-x fs \
|
||||
--insert-global-vars=__filename,__dirname -o preload.js
|
||||
```
|
||||
|
||||
The `-x` flag should be used with any required module that is already exposed in
|
||||
the preload scope, and tells browserify to use the enclosing `require` function
|
||||
|
|
|
@ -140,7 +140,7 @@ option is ignored and `pacScript` configuration is applied.
|
|||
|
||||
The `proxyRules` has to follow the rules below:
|
||||
|
||||
```
|
||||
```sh
|
||||
proxyRules = schemeProxies[";"<schemeProxies>]
|
||||
schemeProxies = [<urlScheme>"="]<proxyURIList>
|
||||
urlScheme = "http" | "https" | "ftp" | "socks"
|
||||
|
|
|
@ -114,7 +114,7 @@ Make sure you have the latest Visual Studio update installed.
|
|||
If building under Cygwin, you may see `bootstrap.py` failed with following
|
||||
error:
|
||||
|
||||
```
|
||||
```bash
|
||||
Assertion failed: ((handle))->activecnt >= 0, file src\win\pipe.c, line 1430
|
||||
|
||||
Traceback (most recent call last):
|
||||
|
|
|
@ -18,7 +18,9 @@ See also [V8 Development](v8-development.md)
|
|||
It is possible to debug Chromium with Electron by passing
|
||||
`--build_debug_libcc` to the bootstrap script:
|
||||
|
||||
$ ./script/bootstrap.py -d --build_debug_libcc
|
||||
```bash
|
||||
$ ./script/bootstrap.py -d --build_debug_libcc
|
||||
```
|
||||
|
||||
This will download and build libchromiumcontent locally, similarly to the
|
||||
`--build_release_libcc`, but it will create a shared library build of
|
||||
|
@ -27,13 +29,17 @@ libchromiumcontent and won't strip any symbols, making it ideal for debugging.
|
|||
When built like this, you can make changes to files in
|
||||
`vendor/libchromiumcontent/src` and rebuild quickly with:
|
||||
|
||||
$ ./script/build.py -c D --libcc
|
||||
```bash
|
||||
$ ./script/build.py -c D --libcc
|
||||
```
|
||||
|
||||
When developing on linux with gdb, it is recommended to add a gdb index to speed
|
||||
up loading symbols. This doesn't need to be executed on every build, but it is
|
||||
recommended to do it at least once to index most shared libraries:
|
||||
recommended to do it at least once to index most shared libraries:
|
||||
|
||||
$ ./vendor/libchromiumcontent/src/build/gdb-add-index ./out/D/electron
|
||||
```bash
|
||||
$ ./vendor/libchromiumcontent/src/build/gdb-add-index ./out/D/electron
|
||||
```
|
||||
|
||||
Building libchromiumcontent requires a powerful machine and takes a long time
|
||||
(though incremental rebuilding the shared library component is fast). With an
|
||||
|
@ -54,13 +60,17 @@ several libchromiumcontent build trees on the same machine(to work on different
|
|||
branches for example), it is recommended to set the variable to speed up the
|
||||
download of Chromium source. For example:
|
||||
|
||||
$ mkdir ~/.chromium-git-cache
|
||||
$ LIBCHROMIUMCONTENT_GIT_CACHE=~/.chromium-git-cache ./script/bootstrap.py -d --build_debug_libcc
|
||||
```bash
|
||||
$ mkdir ~/.chromium-git-cache
|
||||
$ LIBCHROMIUMCONTENT_GIT_CACHE=~/.chromium-git-cache ./script/bootstrap.py -d --build_debug_libcc
|
||||
```
|
||||
|
||||
If the bootstrap script is interrupted while using the git cache, it will leave
|
||||
the cache locked. To remove the lock, delete the files ending in `.lock`:
|
||||
|
||||
$ find ~/.chromium-git-cache/ -type f -name '*.lock' -delete
|
||||
```bash
|
||||
$ find ~/.chromium-git-cache/ -type f -name '*.lock' -delete
|
||||
```
|
||||
|
||||
It is possible to share this directory with other machines by exporting it as
|
||||
SMB share on linux, but only one process/machine can be using the cache at a
|
||||
|
@ -70,6 +80,8 @@ not work perfectly in a network.
|
|||
On Windows, SMBv2 has a directory cache that will cause problems with the git
|
||||
cache script, so it is necessary to disable it by setting the registry key
|
||||
|
||||
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Lanmanworkstation\Parameters\DirectoryCacheLifetime
|
||||
```bash
|
||||
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Lanmanworkstation\Parameters\DirectoryCacheLifetime
|
||||
```
|
||||
|
||||
to 0. More information: https://stackoverflow.com/a/9935126
|
||||
|
|
|
@ -73,7 +73,7 @@ Tips:
|
|||
|
||||
For a `patch` release, use the following format:
|
||||
|
||||
```
|
||||
```sh
|
||||
## Bug Fixes
|
||||
|
||||
* Fixed a cross-platform thing. #123
|
||||
|
@ -95,7 +95,7 @@ For a `patch` release, use the following format:
|
|||
|
||||
For a `minor` release, e.g. `1.8.0`, use this format:
|
||||
|
||||
```
|
||||
```sh
|
||||
## Upgrades
|
||||
|
||||
- Upgraded from Node `oldVersion` to `newVersion`. #123
|
||||
|
@ -118,7 +118,7 @@ For a `minor` release, e.g. `1.8.0`, use this format:
|
|||
```
|
||||
|
||||
### Major releases
|
||||
```
|
||||
```sh
|
||||
## Upgrades
|
||||
|
||||
- Upgraded from Chromium `oldVersion` to `newVersion`. #123
|
||||
|
@ -147,7 +147,7 @@ For a `minor` release, e.g. `1.8.0`, use this format:
|
|||
|
||||
### Beta releases
|
||||
Use the same formats as the ones suggested above, but add the following note at the beginning of the changelog:
|
||||
```
|
||||
```sh
|
||||
**Note:** This is a beta release and most likely will have have some instability and/or regressions.
|
||||
|
||||
Please file new issues for any bugs you find in it.
|
||||
|
|
|
@ -29,7 +29,7 @@ your symbol path (**Note:** you can replace `c:\code\symbols` with any writable
|
|||
directory on your computer, if you'd prefer a different location for downloaded
|
||||
symbols):
|
||||
|
||||
```
|
||||
```powershell
|
||||
SRV*c:\code\symbols\*https://electron-symbols.githubapp.com
|
||||
```
|
||||
|
||||
|
@ -37,7 +37,7 @@ Set this string as `_NT_SYMBOL_PATH` in the environment, using the Windbg menus,
|
|||
or by typing the `.sympath` command. If you would like to get symbols from
|
||||
Microsoft's symbol server as well, you should list that first:
|
||||
|
||||
```
|
||||
```powershell
|
||||
SRV*c:\code\symbols\*http://msdl.microsoft.com/download/symbols;SRV*c:\code\symbols\*https://electron-symbols.githubapp.com
|
||||
```
|
||||
|
||||
|
@ -50,7 +50,7 @@ SRV*c:\code\symbols\*http://msdl.microsoft.com/download/symbols;SRV*c:\code\symb
|
|||
|
||||
Type the following commands in Windbg to print why symbols are not loading:
|
||||
|
||||
```
|
||||
```powershell
|
||||
> !sym noisy
|
||||
> .reload /f electron.exe
|
||||
```
|
||||
|
|
|
@ -9,7 +9,7 @@ to understand the source code better.
|
|||
|
||||
## Structure of Source Code
|
||||
|
||||
```
|
||||
```sh
|
||||
Electron
|
||||
├── atom/ - C++ source code.
|
||||
| ├── app/ - System entry code.
|
||||
|
@ -85,7 +85,7 @@ git submodule update --init --recursive
|
|||
If you find yourself running this command often, you can create an alias for it
|
||||
in your `~/.gitconfig` file:
|
||||
|
||||
```
|
||||
```sh
|
||||
[alias]
|
||||
su = submodule update --init --recursive
|
||||
```
|
||||
|
|
18
docs/faq.md
18
docs/faq.md
|
@ -2,17 +2,17 @@
|
|||
|
||||
## Why am I having trouble installing Electron?
|
||||
|
||||
When running `npm install electron`, some users occasionally encounter
|
||||
When running `npm install electron`, some users occasionally encounter
|
||||
installation errors.
|
||||
|
||||
In almost all cases, these errors are the result of network problems and not
|
||||
actual issues with the `electron` npm package. Errors like `ELIFECYCLE`,
|
||||
`EAI_AGAIN`, `ECONNRESET`, and `ETIMEDOUT` are all indications of such
|
||||
network problems. The best resolution is to try switching networks, or
|
||||
In almost all cases, these errors are the result of network problems and not
|
||||
actual issues with the `electron` npm package. Errors like `ELIFECYCLE`,
|
||||
`EAI_AGAIN`, `ECONNRESET`, and `ETIMEDOUT` are all indications of such
|
||||
network problems. The best resolution is to try switching networks, or
|
||||
just wait a bit and try installing again.
|
||||
|
||||
You can also attempt to download Electron directly from
|
||||
[electron/electron/releases](https://github.com/electron/electron/releases)
|
||||
You can also attempt to download Electron directly from
|
||||
[electron/electron/releases](https://github.com/electron/electron/releases)
|
||||
if installing via `npm` is failing.
|
||||
|
||||
## When will Electron upgrade to latest Chrome?
|
||||
|
@ -134,7 +134,7 @@ delete window.module;
|
|||
|
||||
When using Electron's built-in module you might encounter an error like this:
|
||||
|
||||
```
|
||||
```sh
|
||||
> require('electron').webFrame.setZoomFactor(1.0)
|
||||
Uncaught TypeError: Cannot read property 'setZoomLevel' of undefined
|
||||
```
|
||||
|
@ -151,7 +151,7 @@ console.log(require.resolve('electron'))
|
|||
|
||||
and then check if it is in the following form:
|
||||
|
||||
```
|
||||
```sh
|
||||
"/path/to/Electron.app/Contents/Resources/atom.asar/renderer/api/lib/exports/electron.js"
|
||||
```
|
||||
|
||||
|
|
|
@ -168,7 +168,7 @@ The optional arguments are notated by square brackets `[]` surrounding the optio
|
|||
as well as the comma required if this optional argument follows another
|
||||
argument:
|
||||
|
||||
```
|
||||
```sh
|
||||
required[, optional]
|
||||
```
|
||||
|
||||
|
|
|
@ -80,7 +80,7 @@ file's name.
|
|||
|
||||
The structure of a renamed app would be like:
|
||||
|
||||
```
|
||||
```text
|
||||
MyApp.app/Contents
|
||||
├── Info.plist
|
||||
├── MacOS/
|
||||
|
@ -140,7 +140,7 @@ we appreciate your help.
|
|||
|
||||
2. Create a new S3 bucket and create the following empty directory structure:
|
||||
|
||||
```
|
||||
```sh
|
||||
- atom-shell/
|
||||
- symbols/
|
||||
- dist/
|
||||
|
@ -157,7 +157,7 @@ we appreciate your help.
|
|||
* `CI` - Set to `true` or else it will fail
|
||||
* `GITHUB_TOKEN` - set it to the same as `ELECTRON_GITHUB_TOKEN`
|
||||
* `SURF_TEMP` - set to `C:\Temp` on Windows to prevent path too long issues
|
||||
* `TARGET_ARCH` - set to `ia32` or `x64`
|
||||
* `TARGET_ARCH` - set to `ia32` or `x64`
|
||||
|
||||
4. In `script/upload.py`, you _must_ set `ELECTRON_REPO` to your fork (`MYORG/electron`),
|
||||
especially if you are a contributor to Electron proper.
|
||||
|
|
|
@ -6,7 +6,7 @@ If you've been using Node and npm for a while, you are probably aware of [Semant
|
|||
|
||||
Semantic versions are always made up of three numbers:
|
||||
|
||||
```
|
||||
```sh
|
||||
major.minor.patch
|
||||
```
|
||||
|
||||
|
@ -18,7 +18,7 @@ Semantic version numbers are bumped (incremented) using the following rules:
|
|||
|
||||
A simple mnemonic for remembering this scheme is as follows:
|
||||
|
||||
```
|
||||
```sh
|
||||
breaking.feature.fix
|
||||
```
|
||||
|
||||
|
@ -35,11 +35,11 @@ This system had a number of drawbacks, such as:
|
|||
- New bugs could be introduced into a new patch version because patch versions added features
|
||||
- It didn't follow SemVer so it could confuse consumers
|
||||
- It wasn't clear what the differences between stable and beta builds were
|
||||
- The lack of a formalized stabilization process and release schedule lead to sporadic releases and betas that could last several months
|
||||
- The lack of a formalized stabilization process and release schedule lead to sporadic releases and betas that could last several months
|
||||
|
||||
## Version 2 and Beyond
|
||||
|
||||
From version 2.0.0, Electron will attempt to adhere to SemVer and follow a
|
||||
From version 2.0.0, Electron will attempt to adhere to SemVer and follow a
|
||||
release schedule and stabilization process similar to that of Chromium.
|
||||
|
||||
### Version Change Rules
|
||||
|
@ -67,11 +67,11 @@ will be prefixed with a caret `^` in package.json:
|
|||
}
|
||||
```
|
||||
|
||||
The [caret semver range](https://docs.npmjs.com/misc/semver#caret-ranges-123-025-004)
|
||||
allows minor- and patch-level changes to be installed, i.e. non-breaking
|
||||
The [caret semver range](https://docs.npmjs.com/misc/semver#caret-ranges-123-025-004)
|
||||
allows minor- and patch-level changes to be installed, i.e. non-breaking
|
||||
features and bug fixes.
|
||||
|
||||
Alternatively, a more conservative approach is to use the
|
||||
Alternatively, a more conservative approach is to use the
|
||||
[tilde semver range](https://docs.npmjs.com/misc/semver#tilde-ranges-123-12-1)
|
||||
`~`, which will only allow patch-level upgrades, i.e. bug fixes.
|
||||
|
||||
|
@ -88,28 +88,28 @@ Here are some important points to call out:
|
|||
- A new release is performed approximately weekly.
|
||||
- Minor versions are branched off of master for stabilization.
|
||||
- The stabilization period is approximately weekly.
|
||||
- Important bug fixes are cherry-picked to stabilization branches after landing
|
||||
- Important bug fixes are cherry-picked to stabilization branches after landing
|
||||
in master.
|
||||
- Features are not cherry picked; a minor version should only get *more stable*
|
||||
- Features are not cherry picked; a minor version should only get *more stable*
|
||||
with its patch versions.
|
||||
- There is little difference in the release schedule between a major and minor
|
||||
- There is little difference in the release schedule between a major and minor
|
||||
release, other than the risk/effort it may take for third parties to adopt
|
||||
- Chromium updates will be performed as fast as the team can manage. In an ideal
|
||||
world this would happen every 6 weeks to align with
|
||||
- Chromium updates will be performed as fast as the team can manage. In an ideal
|
||||
world this would happen every 6 weeks to align with
|
||||
[Chromium's release schedule][Chromium release].
|
||||
- Excluding exceptional circumstances, only the previous stable build will
|
||||
- Excluding exceptional circumstances, only the previous stable build will
|
||||
get backported bug fixes.
|
||||
|
||||
### The Beta Process
|
||||
|
||||
Electron relies on its consumers getting involved in stabilization. The short
|
||||
target stabilization period and rapid release cadence was designed for shipping
|
||||
Electron relies on its consumers getting involved in stabilization. The short
|
||||
target stabilization period and rapid release cadence was designed for shipping
|
||||
security and bug fixes out fast and to encourage the automation of testing.
|
||||
|
||||
You can install the beta by specifying the `beta` dist tag when installing via
|
||||
You can install the beta by specifying the `beta` dist tag when installing via
|
||||
npm:
|
||||
|
||||
```
|
||||
```sh
|
||||
npm install electron@beta
|
||||
```
|
||||
|
||||
|
|
|
@ -183,13 +183,13 @@ $ ./node_modules/.bin/electron .
|
|||
|
||||
#### Windows
|
||||
|
||||
```
|
||||
```bash
|
||||
$ .\node_modules\.bin\electron .
|
||||
```
|
||||
|
||||
#### Node v8.2.0 and later
|
||||
|
||||
```
|
||||
```bash
|
||||
$ npx electron .
|
||||
```
|
||||
|
||||
|
@ -212,7 +212,7 @@ $ ./electron/electron your-app/
|
|||
|
||||
#### Windows
|
||||
|
||||
```
|
||||
```bash
|
||||
$ .\electron\electron.exe your-app\
|
||||
```
|
||||
|
||||
|
|
|
@ -23,7 +23,7 @@ commands with `xvfb-maybe` and the little tool will automatically configure
|
|||
xvfb, if required by the current system. On Windows or macOS, it will simply
|
||||
do nothing.
|
||||
|
||||
```
|
||||
```sh
|
||||
## On Windows or macOS, this just invokes electron-mocha
|
||||
## On Linux, if we are in a headless environment, this will be equivalent
|
||||
## to xvfb-run electron-mocha ./test/*.js
|
||||
|
|
|
@ -36,7 +36,7 @@ requirements:
|
|||
|
||||
Then, go and install the `electron-windows-store` CLI:
|
||||
|
||||
```
|
||||
```sh
|
||||
npm install -g electron-windows-store
|
||||
```
|
||||
|
||||
|
@ -48,7 +48,7 @@ any module you don't actually need will just increase your application's size.
|
|||
|
||||
The output should look roughly like this:
|
||||
|
||||
```
|
||||
```text
|
||||
├── Ghost.exe
|
||||
├── LICENSE
|
||||
├── content_resources_200_percent.pak
|
||||
|
@ -79,7 +79,7 @@ From an elevated PowerShell (run it "as Administrator"), run
|
|||
and output directories, the app's name and version, and confirmation that
|
||||
`node_modules` should be flattened.
|
||||
|
||||
```
|
||||
```powershell
|
||||
electron-windows-store `
|
||||
--input-directory C:\myelectronapp `
|
||||
--output-directory C:\output\myelectronapp `
|
||||
|
|
|
@ -17,6 +17,8 @@
|
|||
"husky": "^0.14.3",
|
||||
"minimist": "^1.2.0",
|
||||
"nugget": "^2.0.1",
|
||||
"remark-cli": "^4.0.0",
|
||||
"remark-preset-lint-markdown-style-guide": "^2.1.1",
|
||||
"request": "^2.68.0",
|
||||
"standard": "^8.4.0",
|
||||
"standard-markdown": "^4.0.0",
|
||||
|
@ -48,7 +50,7 @@
|
|||
"lint-js": "standard && cd spec && standard",
|
||||
"lint-cpp": "python ./script/cpplint.py",
|
||||
"lint-py": "python ./script/pylint.py",
|
||||
"lint-docs": "npm run lint-js-in-markdown && npm run create-typescript-definitions",
|
||||
"lint-docs": "remark docs -qf && npm run lint-js-in-markdown && npm run create-typescript-definitions",
|
||||
"lint-js-in-markdown": "standard-markdown docs",
|
||||
"create-api-json": "electron-docs-linter docs --outfile=out/electron-api.json --version=$npm_package_version",
|
||||
"create-typescript-definitions": "npm run create-api-json && electron-typescript-definitions --in=out/electron-api.json --out=out/electron.d.ts",
|
||||
|
|
|
@ -161,11 +161,11 @@ def safe_mkdir(path):
|
|||
raise
|
||||
|
||||
|
||||
def execute(argv, env=os.environ):
|
||||
def execute(argv, env=os.environ, cwd=None):
|
||||
if is_verbose_mode():
|
||||
print ' '.join(argv)
|
||||
try:
|
||||
output = subprocess.check_output(argv, stderr=subprocess.STDOUT, env=env)
|
||||
output = subprocess.check_output(argv, stderr=subprocess.STDOUT, env=env, cwd=cwd)
|
||||
if is_verbose_mode():
|
||||
print output
|
||||
return output
|
||||
|
@ -183,7 +183,7 @@ def execute_stdout(argv, env=os.environ, cwd=None):
|
|||
print e.output
|
||||
raise e
|
||||
else:
|
||||
execute(argv, env)
|
||||
execute(argv, env, cwd)
|
||||
|
||||
|
||||
def electron_gyp():
|
||||
|
|
Loading…
Reference in a new issue