Documenation Linting and TOC generation #3841

brandonocasey · 2016-12-07T22:57:13Z

Description

Use remark to lint, fix formatting of docs, and add a toc if there is a table of contents heading.

Requirements Checklist

Feature implemented / Bug fixed
If necessary, more likely in a feature request than a bug fix
- Docs/guides updated
Reviewed by Two Core Contributors

gkatsev · 2016-12-07T23:13:38Z

COLLABORATOR_GUIDE.md


-    Update TOC
-```
+    commit 433c58224f5be34480c8e067ca6c5406ba1c1e9c


code fences are better

gkatsev · 2016-12-07T23:14:34Z

CONTRIBUTING.md

-1. Use the [GitHub issue search](https://github.com/videojs/video.js/issues) &mdash; check if the issue has already been reported.
-
-1. Check if the issue has already been fixed &mdash; try to reproduce it using the latest `master` branch in the repository.
+2. Use the [GitHub issue search](https://github.com/videojs/video.js/issues) — check if the issue has already been reported.


Using 1. for everything makes maintain the doc a lot easier because if you add items or move stuff around you don't need to re-do the entire list.

ok I can change the linting rules to that

misteroneill · 2016-12-09T21:05:35Z

COLLABORATOR_GUIDE.md

+    * [GitHub personal access token](#github-personal-access-token)
+
+  * [Doing a release](#doing-a-release)
+* [Doc credit](#doc-credit)


I like this a lot better than the doctoc mess. Does it key off the ## Table of Contents heading or what?

yeah looks for the first heading called "Table of Contents". We could even rename the heading via an option. If we wanted to. Although I think Table of Contents makes the most sense.

misteroneill

This looks awesome. Love it.

gkatsev · 2016-12-13T20:47:17Z

CONTRIBUTING.md

-Any testing considerations or things to think about when looking at the commit.
-
-Fixes #123. The footer can contain Fixes messages.
+```txt


I think this one got messed up in the automation. It supposed to look something like

fix: one line commit explanation In the body of the commit message, we can talk about why we made the change. What the change entails. Any testing considerations or things to think about when looking at the commit. Fixes #123. The footer can contain Fixes messages.

I may have changed it somehow, I put it back to what it was

gkatsev · 2016-12-20T17:02:48Z

COLLABORATOR_GUIDE.md

+  * [Involving the TSC](#involving-the-tsc)
+* [Landing a PR](#landing-a-pr)
+  * [Landing a PR manually](#landing-a-pr-manually)
+


a lot of whitespace is added to TOCs which I think makes the output look worse.

Looks like the TOC whitespace is a bug. I made a PR to fix it: syntax-tree/mdast-util-toc#3

gkatsev · 2016-12-20T17:05:42Z

COLLABORATOR_GUIDE.md

@@ -77,7 +78,7 @@ The footer should contain things like whether this is a breaking change or what

 Here's an example:

-```
+```commit


huh, didn't realize they had a thing for that.

gkatsev · 2016-12-20T17:08:33Z

COLLABORATOR_GUIDE.md

 [issue template]: /.github/ISSUE_TEMPLATE.md
+


I think this whitespace makes things worse.

gkatsev · 2016-12-20T17:12:21Z

README.md

 [browserstack]: https://browserstack.com
-[buildwith]: https://trends.builtwith.com/media/VideoJS
+


👎 to all this whitespace. If these links where visible as is, it might make more sense but it just makes maintaining these a bit worse, I think.

Doesn't seem like there's an option for remark for this right now. I'll keep my eye on it.

Opened #3882 to track fixing it in the future.

gkatsev · 2016-12-20T17:13:54Z

docs/guides/components.md

 The default component structure of the Video.js player looks something like this:

-```
+```tree


gkatsev · 2016-12-20T17:16:23Z

docs/guides/options.md

+## Table of Contents
+
+* [Standard &lt;video> Element Options](#standard-video-element-options)
+  * [autoplay](#autoplay)


Interesting that this stripped out the backticks.

gkatsev · 2016-12-20T17:18:26Z

docs/guides/options.md


+> Type: `boolean`, Default: `false`


there needs to be a new line after this because otherwise the Type and the Note come out on the same line.

gkatsev · 2016-12-20T17:24:35Z

package.json

@@ -25,7 +25,9 @@
    "start": "grunt watchAll",
    "test": "grunt test",
    "toc": "doctoc",
-    "docs": "jsdoc -r src/js -d docs/api -c .jsdoc.json"


docs should probably lint and then generate the api docs. something like

npm run docs:lint && npm run docs:api

gkatsev · 2016-12-20T17:25:07Z

package.json

@@ -25,7 +25,9 @@
    "start": "grunt watchAll",
    "test": "grunt test",
    "toc": "doctoc",


if we're moving to remark for TOCs, we should remove doctoc and this script.

misteroneill · 2016-12-20T21:01:06Z

package.json

@@ -24,8 +24,10 @@
    "lint": "vjsstandard",
    "start": "grunt watchAll",
    "test": "grunt test",
-    "toc": "doctoc",
-    "docs": "jsdoc -r src/js -d docs/api -c .jsdoc.json"
+    "docs": "npm run docs:lint && npm run docs:api",


Should this run docs:fix?

I was thinking that this would be something that we could run as part of the build process to lint our markdown files and generate the API docs. In that case, I wouldn't want any other changes to be made to the markdown files. However, the build process could always call these two manually instead.

experimental doc tooling and updates

515c59a

gkatsev reviewed Dec 7, 2016

View reviewed changes

brandonocasey added 2 commits December 8, 2016 14:05

new linting rules, better configuration and tooling

2dbe586

make some things errors

f9ebf18

brandonocasey changed the title ~~experimental doc tooling and updates~~ Documenation Linting, TOC generation, and builds Dec 8, 2016

brandonocasey changed the title ~~Documenation Linting, TOC generation, and builds~~ Documenation Linting and TOC generation Dec 8, 2016

misteroneill reviewed Dec 9, 2016

View reviewed changes

misteroneill approved these changes Dec 9, 2016

View reviewed changes

brandonocasey mentioned this pull request Dec 12, 2016

Fix API documentation generation #3854

Merged

2 tasks

brandonocasey added confirmed documentation labels Dec 13, 2016

gkatsev reviewed Dec 13, 2016

View reviewed changes

brandonocasey and others added 2 commits December 13, 2016 16:00

automation revert

4c91f1d

Merge branch 'master' into chore/doc-tools

62e77fe

gkatsev requested changes Dec 20, 2016

View reviewed changes

gkatsev added 4 commits December 20, 2016 13:43

add extra whitespace in sourceOrder option

0c68d06

remove extra whitespace

44e0293

fix docs

d225b7b

remove doctoc, add docs script

91e3b70

gkatsev approved these changes Dec 20, 2016

View reviewed changes

misteroneill reviewed Dec 20, 2016

View reviewed changes

gkatsev merged commit 0493f54 into videojs:master Dec 20, 2016

brandonocasey deleted the chore/doc-tools branch February 2, 2017 21:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documenation Linting and TOC generation #3841

Documenation Linting and TOC generation #3841

brandonocasey commented Dec 7, 2016 •

edited by mmcc

Loading

gkatsev Dec 7, 2016

misteroneill Dec 13, 2016

gkatsev Dec 7, 2016

brandonocasey Dec 8, 2016

misteroneill Dec 9, 2016

brandonocasey Dec 9, 2016

misteroneill left a comment

gkatsev Dec 13, 2016

brandonocasey Dec 13, 2016

gkatsev Dec 20, 2016

gkatsev Dec 20, 2016

gkatsev Dec 20, 2016

gkatsev Dec 20, 2016

gkatsev Dec 20, 2016

gkatsev Dec 20, 2016

gkatsev Dec 20, 2016

gkatsev Dec 20, 2016

gkatsev Dec 20, 2016

gkatsev Dec 20, 2016

gkatsev Dec 20, 2016

gkatsev Dec 20, 2016

gkatsev Dec 20, 2016

gkatsev Dec 20, 2016

misteroneill Dec 20, 2016

gkatsev Dec 20, 2016

		[browserstack]: https://browserstack.com
		[buildwith]: https://trends.builtwith.com/media/VideoJS

Documenation Linting and TOC generation #3841

Documenation Linting and TOC generation #3841

Conversation

brandonocasey commented Dec 7, 2016 • edited by mmcc Loading

Description

Requirements Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

misteroneill left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brandonocasey commented Dec 7, 2016 •

edited by mmcc

Loading