build: move to the new docs parser #18103
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
52ae92e to
d24c458
Compare
|
So the diff in the https://gist.github.com/MarshallOfSound/14fdce4022c3453eeb24c7520f0c8356 And here is the actual new file: https://gist.github.com/MarshallOfSound/7773cc6501a303fa6dfb62792d477ba1 |
0f34737 to
4fd63bd
Compare
4fd63bd to
07c7172
Compare
malept
reviewed
May 3, 2019
Co-Authored-By: MarshallOfSound <samuel.r.attard@gmail.com>
malept
reviewed
May 3, 2019
Co-Authored-By: MarshallOfSound <samuel.r.attard@gmail.com>
jkleinsc
approved these changes
May 6, 2019
|
Release Notes Persisted
|
kiku-jw
pushed a commit
to kiku-jw/electron
that referenced
this pull request
May 16, 2019
* build: move to the new docs parser * chore: remove the bad getTitle param doc * build: update parser/ts gen deps + fix some docs issues highlighted by GH desktop * chore: apply suggestions from code review Co-Authored-By: MarshallOfSound <samuel.r.attard@gmail.com> * chore: update docs for accidentally removed things * chore: update docs/api/command-line.md Co-Authored-By: MarshallOfSound <samuel.r.attard@gmail.com>
3 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Switched from:
electron-docs-linter-->@electron/docs-parserelectron-typescript-definitions-->@electron/typescript-definitionsThis makes our definition file way better, we don't lose any information in the docs. Noticeably this means markdown, links and code blocks are persisted in the TS definitions. It is also much better under the hood so future improvements / fixes will be much easier. E.g.
readonlysupport is in a branch somewhere :)I'm planning on writing a blog post at some point detailing how
@electron/docs-parsernow works. But from a thousand foot view.doc-linterused to parse the markdown in HTML and then parse the docs as a DOM structure withjqueryand selector querying. This had a few issues the biggest being it was very hard to semantically now what was "inside" a heading when the generated HTML just looks like this:The new
docs-parsermodule parses the markdown file into a markdown AST which does know where things start and end so it makes parsing things way easier and it means we can losslessly maintain the markdown in each block without worrying about HTML entities or escaping or anything like that.This PR also fixes a bunch of issues with a current documentation, highlights below.
app.commandLine.*andapp.dock.*are now in separate "module" files. Lumping them in withapp.mdover-complicated the parser and the read experience.Eventdocumentation not havingReturns:(the magic keyword to document the event properties)-and:and\nso that documentation for properties in deep objects are correctly parsed.Notes: Switched to a new Typescript Definitions generator. This means that some interface names may have changed, if your Typescript build is failing this is the cause.