Skip to content
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’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[feat] Linter documentation in GitHub Pages. #263

Merged
merged 2 commits into from
Oct 31, 2019

Conversation

lukesneeringer
Copy link
Contributor

This (incredibly large) PR adds a docs/ directory that we can serve with GitHub Pages.

It provides documentation for three linter rules; the remainder will come in follow-up PRs.

Note that as part of this, I intend to enforce (and soon lint for) some consistency on linter rules, including:

  • One rule per file.
  • The rule's filename must be derived from the rule name
    (converting - to _ but no other changes).

This is to make things like "View Implmenetation" easy.

This (incredibly large) PR adds a `docs/` directory that we can
serve with GitHub Pages.

It provides documentation for three linter rules; the remainder
will come in follow-up PRs.

Note that as part of this, I intend to enforce (and soon lint for)
some consistency on linter rules, including:

- One rule per file.
- The rule's filename must be derived from the rule name
  (converting `-` to `_` but no other changes).

This is to make things like "View Implmenetation" easy.
@lukesneeringer lukesneeringer requested a review from a team October 31, 2019 00:31
@googlebot googlebot added the cla: yes This human has signed the Contributor License Agreement. label Oct 31, 2019
@lukesneeringer
Copy link
Contributor Author

The front page looks nice, but needs installation instructions (which can also come in a followup, preferably by not-me):

Screen Shot 2019-10-30 at 5 25 40 PM

@lukesneeringer
Copy link
Contributor Author

The base page for rule documentation will eventually have tiles for the groups of rules. Right now only core has any rules implemented, so there is only one. This is fine.

Screen Shot 2019-10-30 at 5 25 51 PM

@lukesneeringer
Copy link
Contributor Author

The rule listing has an expandable "zippy" for each AIP:

Screen Shot 2019-10-30 at 5 25 59 PM

@lukesneeringer
Copy link
Contributor Author

Each rule gets a page, like in the internal linter. There is a quick button on the right that takes you to the implementation code in GitHub. Incorrect and correct code get the red or green line on the side, which interacts better with syntax highlighting than does changing the background color:

Screen Shot 2019-10-30 at 5 26 22 PM

@lukesneeringer
Copy link
Contributor Author

The page overall looks good on mobile, although protos that are too wide will cause horizontal scrolling, as seen in the comments. That's probably just life.

Screen Shot 2019-10-30 at 5 27 10 PM

@lukesneeringer
Copy link
Contributor Author

Print mode looks good too, although I need to figure out what is up with the big blank space on the top. I bet that is broken on the AIP site also.

Note that the incorrect and correct protos now start with // Incorrect. and // Correct. (That's actually the magic that causes the green and red lines in the screen mode; I intentionally throw away those comments on the screen but preserve them in print.

Screen Shot 2019-10-30 at 5 27 59 PM

@lukesneeringer
Copy link
Contributor Author

This is not perfect, but it is definitely good enough. I want to merge it and then make incremental improvements. This will also unblock getting documentation written for other rules.

Copy link
Contributor

@mingzhi mingzhi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The pages look wonderful!!! And thank you so much for walkthrough on different pages! I quickly approved this PR without deep review. And as you said, we can make more incremental changes after this PR.

@lukesneeringer lukesneeringer merged commit fbed405 into master Oct 31, 2019
@lukesneeringer lukesneeringer deleted the github-pages-docs branch October 31, 2019 03:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cla: yes This human has signed the Contributor License Agreement.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants