New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation Overhaul #11966

Merged
merged 26 commits into from Feb 21, 2018

Conversation

Projects
None yet
7 participants
@felixrieseberg
Member

felixrieseberg commented Feb 20, 2018

Apologies for the giant pull request. This is an effort @zeke and I have discussed over and over again and I finally found the time to dig into it.

In essence, this PR takes our existing documentation (everything in the docs/tutorial folder) and creates a clear progression. I have then taken the most obvious holes and filled those in with new documentation. In addition, I have cleaned up all tutorials to use roughly the same style, variable names, and conventions. I also fixed dead links.

This is simply a start. This PR isn't meant to be the end-all of what our documentation looks like, it's merely supposed to be better than what we have today. Today, our documentation is a loose collection of files sorted alphabetically (the "How to build a custom developer tools extension" file comes before the "How to install Electron", because, well, I comes after D...).

馃摑 Table of contents

In summary:

Also in summary, thanks to @codebytere:

fjpcmty

@felixrieseberg felixrieseberg requested a review from electron/docs as a code owner Feb 20, 2018

@malept

馃憤 for the reorganization of the docs

Show outdated Hide outdated docs/tutorial/boilerplates-and-clis.md
and renderer processes. Like [`ipcRenderer`](../api/ipc-renderer.md) and
[`ipcMain`](../api/ipc-main.md) modules for sending messages, and the
[remote](../api/remote.md) module for RPC style communication. There is also
an FAQ entry on [how to share data between web pages][share-data].

This comment has been minimized.

@malept

malept Feb 20, 2018

Member

Missing link

@malept

malept Feb 20, 2018

Member

Missing link

This comment has been minimized.

@felixrieseberg

felixrieseberg Feb 20, 2018

Member

Thanks, fixed!

@felixrieseberg

felixrieseberg Feb 20, 2018

Member

Thanks, fixed!

Show outdated Hide outdated docs/README.md
Show outdated Hide outdated docs/README.md
Show outdated Hide outdated docs/tutorial/unity-launcher.md
Show outdated Hide outdated docs/README.md
@zeke

This comment has been minimized.

Show comment
Hide comment
@zeke

zeke Feb 20, 2018

Member

@felixrieseberg this is so good it almost makes me want to cry. Thank you so much for moving this forward. I'll review it in earnest tomorrow.

Member

zeke commented Feb 20, 2018

@felixrieseberg this is so good it almost makes me want to cry. Thank you so much for moving this forward. I'll review it in earnest tomorrow.

Debugging the main process is a bit trickier, since you cannot simply open
developer tools for them. The Chromium Developer Tools can [be used
to debug Electron's main process][node-inspect] thanks to a closer collaboration
between Google / Chrome and Node.js, but you might encounter oddities like

This comment has been minimized.

@YurySolovyov

YurySolovyov Feb 20, 2018

Contributor

"closer integration between Chrome and Node.js" maybe?

@YurySolovyov

YurySolovyov Feb 20, 2018

Contributor

"closer integration between Chrome and Node.js" maybe?

you will merely need Node.js, npm, a code editor of your choice, and a
rudimentary understanding of your operating system's command line client.
## Setting up macOS

This comment has been minimized.

@YurySolovyov

YurySolovyov Feb 20, 2018

Contributor

shouldn't there be on here? Setting up on macOS, Setting up on Windows, etc.

@YurySolovyov

YurySolovyov Feb 20, 2018

Contributor

shouldn't there be on here? Setting up on macOS, Setting up on Windows, etc.

This comment has been minimized.

@felixrieseberg

felixrieseberg Feb 20, 2018

Member

The point is: "Setting up Windows for Electron development" or "Setting up Windows as a developer environment for Electron."

@felixrieseberg

felixrieseberg Feb 20, 2018

Member

The point is: "Setting up Windows for Electron development" or "Setting up Windows as a developer environment for Electron."

<h1>Hello World!</h1>
We are using node <script>document.write(process.versions.node)</script>,
Chrome <script>document.write(process.versions.chrome)</script>,
and Electron <script>document.write(process.versions.electron)</script>.

This comment has been minimized.

@YurySolovyov

YurySolovyov Feb 20, 2018

Contributor

I'm not sure which API is better, but I think we should not encourage using document.write ever.
Maybe use .innerHTML accessor on some tag?

@YurySolovyov

YurySolovyov Feb 20, 2018

Contributor

I'm not sure which API is better, but I think we should not encourage using document.write ever.
Maybe use .innerHTML accessor on some tag?

This comment has been minimized.

@felixrieseberg

felixrieseberg Feb 20, 2018

Member

I know that it's real tempting to use this PR to change all our docs, but let's not bikeshed this here - this is the existing electron-quick-start and in the current docs. We can totally improve it, but I think this PR is already big enough that I'd like to focus on the changes.

@felixrieseberg

felixrieseberg Feb 20, 2018

Member

I know that it's real tempting to use this PR to change all our docs, but let's not bikeshed this here - this is the existing electron-quick-start and in the current docs. We can totally improve it, but I think this PR is already big enough that I'd like to focus on the changes.

Show outdated Hide outdated docs/README.md
Show outdated Hide outdated docs/README.md
```javascript
const fs = require('fs')
const root = fs.readdirSync('/')

This comment has been minimized.

@zeke

zeke Feb 20, 2018

Member

Does this line work on windows? Home about os.homedir() instead?

@zeke

zeke Feb 20, 2018

Member

Does this line work on windows? Home about os.homedir() instead?

This comment has been minimized.

@felixrieseberg

felixrieseberg Feb 21, 2018

Member

It does! It returns C:\ by default 馃憤

@felixrieseberg

felixrieseberg Feb 21, 2018

Member

It does! It returns C:\ by default 馃憤

Show outdated Hide outdated docs/README.md
@zeke

zeke approved these changes Feb 20, 2018

Boy howdy! What a great set of additions.

I found a few typos and made a few suggestions. Feel free to dismiss the big requests though, because as you said this PR is intended to be an improvement on what we already have, rather than the be-all end-all of Electron tutorial documentation.

@@ -0,0 +1,73 @@
# Boilerplates and CLIs
Electron development is un-opinionated - there is no "one true way" to develop,

This comment has been minimized.

@zeke

zeke Feb 20, 2018

Member

馃挍

@zeke

zeke Feb 20, 2018

Member

馃挍

Show outdated Hide outdated docs/tutorial/boilerplates-and-clis.md
Show outdated Hide outdated docs/tutorial/development-environment.md
Show outdated Hide outdated docs/tutorial/development-environment.md
as a variant of the Node.js runtime that is focused on desktop applications
instead of web servers.
This doesn't mean Electron is a JavaScript binding to graphical user interface

This comment has been minimized.

@zeke

zeke Feb 20, 2018

Member

馃挌

@zeke

zeke Feb 20, 2018

Member

馃挌

a simple Node application, you would add a `start` script that instructs `node`
to execute the current package:
```json

This comment has been minimized.

@zeke

zeke Feb 20, 2018

Member

I don't feel strongly about it, but this indented JSON style is not consistent what npm does. Any changes like --save would blow this formatting away.

@zeke

zeke Feb 20, 2018

Member

I don't feel strongly about it, but this indented JSON style is not consistent what npm does. Any changes like --save would blow this formatting away.

This comment has been minimized.

@felixrieseberg

felixrieseberg Feb 21, 2018

Member

I'm with you. This was in original docs but is easy enough that I fixed it here 馃憤

@felixrieseberg

felixrieseberg Feb 21, 2018

Member

I'm with you. This was in original docs but is easy enough that I fixed it here 馃憤

Show outdated Hide outdated docs/tutorial/first-app.md

@vanessayuenn vanessayuenn merged commit 8e51659 into master Feb 21, 2018

9 checks passed

WIP ready for review
Details
ci/circleci: electron-linux-arm Your tests passed on CircleCI!
Details
ci/circleci: electron-linux-arm-test Your tests passed on CircleCI!
Details
ci/circleci: electron-linux-arm64 Your tests passed on CircleCI!
Details
ci/circleci: electron-linux-arm64-test Your tests passed on CircleCI!
Details
ci/circleci: electron-linux-ia32 Your tests passed on CircleCI!
Details
ci/circleci: electron-linux-x64 Your tests passed on CircleCI!
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/jenkins/pr-head This commit looks good
Details

@vanessayuenn vanessayuenn deleted the documentation-overhaul branch Feb 21, 2018

@zeke zeke referenced this pull request Mar 20, 2018

Merged

add development README #12373

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment