[docs] adds optional capability to provide code examples in rules' metadata #3602

aervin · 2017-12-21T23:45:37Z

PR checklist

Addresses an existing issue: #3601
New feature, bugfix, or enhancement
- Includes tests
Documentation update

Overview of change:

Adds optional capability to provide code examples (passing and failing) for a given rule.

aervin · 2017-12-22T18:44:31Z

docs/_layouts/rule.html

@@ -5,6 +5,15 @@
 {% if page.descriptionDetails %}
   {{page.descriptionDetails | markdownify}}
 {% endif %}
+
+{% if page.codeExamples %}
+    <h3>Code examples: </h3>


"Code examples (default config)"

ajafff · 2017-12-26T12:50:49Z

src/rules/curlyRule.ts

@@ -72,6 +73,17 @@ export class Rule extends Lint.Rules.AbstractRule {
        type: "functionality",
        typescriptOnly: false,
        hasFix: true,
+        codeExamples: {
+            pass: dedent`


IMO this also needs to support multiple examples for different configurations / options.

codeExamples: { default: { pass: "...", fail: "...", }, "ignore-same-line": { ... }, }

Or maybe just an array with an optional description per object.

From my limited experience with the doc portion of the codebase, I think an array would be simplest. So

codeExamples?: { config: string; /* Or... ? */ pass: string; fail: string; description?: string; /* Optional for cases like example below */ }[]

I think an explicit config example would be a good idea from the doc user's perspective, but will probably cause some metadata bloat in some rules.

{ "rules": { "no-console": true } }

[edit] forgot to include description

aervin · 2018-01-14T15:13:55Z

@ajafff I think this one is ready for further consideration when you find time.

Shinigami92 · 2018-01-14T15:22:05Z

How can I help and add examples to all rules? Should I wait on the merged request and then open a fork and make a branch, or should I make a fork of this current branch in the fork of @aervin?
And how am I able to show up the docs pages local in my browser? It's something with ruby I think?

aervin · 2018-01-14T15:30:03Z

@Shinigami92 I'd hold off on adding examples to old rules as these updates are still subject to change. Eventually, I think it'd be great to update the old rules with code examples like you suggest.

You will need Ruby to build the docs locally. With bundle installed, I'm able to cd into the docs directory and run bundle exec jekyll serve to view local updates. It took me some time to figure out how the source is compiled into Jekyll data. Whenever I make changes to TSLint source files, I run

yarn compile && yarn docs && bundle exec jekyll serve

to ensure that changes in the source metadata are reflected in the Jekyll data.

Shinigami92 · 2018-01-14T15:34:30Z

I will try this when I'm back home. Thx

Shinigami92 · 2018-01-14T19:14:31Z

Here is an installation and how to run the docs in Windows (10):

git clone https://github.com/<username>/tslint.git
cd .\tslint\

npm install -g yarn
npm install
yarn compile
yarn docs

# From here -> Windows 10 Ubuntu Terminal
cd /mnt/<win-drive-letter>/<path-to-project>/tslint/docs
sudo apt-add-repository ppa:brightbox/ruby-ng
sudo apt-get update
sudo apt-get install zlib1g-dev ruby2.3 ruby2.3-dev build-essential
# zlib1g-dev is required for gem nokogiri-1.8.1
sudo gem update
sudo gem install jekyll bundler
bundle install
bundle exec jekyll serve

maybe this can be placed in a file in the project to help other devs ^^

helpfull link: https://jekyllrb.com/docs/windows/

Shinigami92 · 2018-01-14T20:02:35Z

I have started to create some examples.
At the end, please look over my english sentenses, because I'm not a native english speaker ^^ (german)

You can track my changes here:
aervin/tslint@docs/code-examples...Shinigami92:docs/code-examples

Shinigami92 · 2018-01-15T19:14:56Z

@aervin You should respect the code-style of the file:
master...Shinigami92:docs/code-examples
scripts/buildDocs.ts
maybe revert some of the changes in this file

But I don't know why ci/circleci: testNext failes
it has nothing to do with the branch?!

@palantirtech, @ajafff or someone else can check the branch now and make an approved review so then others can add examples to other rules :)

aervin · 2018-01-15T19:24:05Z

@Shinigami92 Can you please clarify, I'm not sure what you mean by "You should respect the code-style of the file"? And the link doesn't take me to a file or anything.

Shinigami92 · 2018-01-15T19:36:04Z

@aervin fixed the link: I mean the file scripts/buildDocs.ts

aervin · 2018-01-15T19:58:51Z

@Shinigami92 I did not make those changes directly. I'm thinking it's from compiling/rebuilding the docs (there's probably a --fix in the process somewhere). Those examples in the photo all violate the project's TSLint config, and all those violations have fixers.

Shinigami92 · 2018-01-15T20:05:33Z

@aervin: Dont forgett to accept this PR: aervin#2
It's only from my fork to your fork ^^

aervin · 2018-01-15T20:07:14Z

@Shinigami92 Once we get confirmation on these doc updates, I'll make that a top priority.

aervin · 2018-04-08T13:08:18Z

@suchanlee or @johnwiseheart can we squeeze this one in? I'm happy to make changes.

suchanlee · 2018-04-09T03:37:19Z

@aervin thanks for your patience. I'll try to review this as soon as I can.

suchanlee · 2018-04-09T03:45:08Z

docs/_sass/_base.scss

+            background: transparent;
+        }
+    }
+    & .code-example.pass {


nit: the code style in this file suggests that & . should be &. and that there should be a new line before each of the blocks. same for &: (applies to all code changes in this file)

I understand about the new lines, but there's a difference between & .code-example and &.code-example, isn't there? Still, I think the &s are unnecessary here (the way they're being used). I'll just remove them entirely.

suchanlee · 2018-04-09T03:47:17Z

docs/_sass/_base.scss

+        }
+    }
+    & .code-example.pass {
+        background-color: #f1fff1 !important;


why is !important needed here and below?
if they're required, please leave a comment on why they're required. If not, remove.
Also, it would be awesome to have the color as a comment (e.g. light red or light green)

suchanlee · 2018-04-09T03:48:58Z

scripts/buildDocs.ts

@@ -148,7 +148,7 @@ function buildSingleModuleDocumentation(documentation: IDocumentation, modulePat
    // tslint:disable-next-line:no-var-requires
    const module = require(modulePath);
    const DocumentedItem = module[documentation.exportName] as Documented;
-    if (DocumentedItem != null && DocumentedItem.metadata != null) {
+    if (DocumentedItem !== null && DocumentedItem.metadata !== null) {


i'd prefer that it stay as != instead of !==. != null checks for both undefined and null whereas with !== we specify for null, which may not be the desired behavior. But happy to revisit if there's a good reason to change to !==!

I believe this was changed as a result of the doc-building process (a pass with --fix maybe?). Anyway, I would never make these sorts of changes deliberately (in a PR).

suchanlee · 2018-04-09T03:54:57Z

docs/_layouts/rule.html

+            {{ codeExample.pass | markdownify }}
+        </div>
+        {% if codeExample.fail %}
+        <h5 style="color: #d14;">Fails</h5>


id prefer all styles in css and outside of markup

suchanlee · 2018-04-09T03:58:48Z

docs/_layouts/rule.html

+        <h4>{{ codeExample.description }}</h4>
+        {{ codeExample.config | markdownify }}
+        <h5>Passes</h5>
+        <div class="code-example pass">


one class naming rule I like is for "decorating" class names, in this case pass and below fail, is to preface them with - (e.g. -pass, -fail) so that css rules for pass or fail wouldn't apply. By prefacing decorator class names with dashes, you know that it wouldn't be affected by other styles since all other styles for prefaced class names would be scoped to a particular class name.

suchanlee · 2018-04-09T04:03:28Z

is the above screenshot up to date? in particular, is all the text still green? (doesn't seem to be that way in the code)

update: looks like all the headers are green for tslint docs. But it looks funky with the green header for fail hmm..

aervin · 2018-04-09T13:17:34Z

That picture above is out of date @suchanlee. The latest push looks something like this:

JoshuaKGoldberg · 2018-04-13T06:49:16Z

src/rules/curlyRule.ts

@@ -72,6 +72,58 @@ export class Rule extends Lint.Rules.AbstractRule {
        type: "functionality",
        typescriptOnly: false,
        hasFix: true,
+        codeExamples: [


These code examples are going to end up taking a lot of space in the source files (good!). What are your thoughts on starting a precedent of putting them in a ruleName.examples.ts file that just exports an object with examples?

@JoshuaKGoldberg I had a similar concern myself. I think the separate file approach makes sense 👍 and will update the curly rule example.

suchanlee · 2018-04-16T01:23:45Z

docs/Gemfile.lock

@@ -0,0 +1,238 @@
+GEM


should this be checked in to the repo? I'm not familiar with gem/gemfile

@suchanlee It looks like the bundler docs suggest checking in the lock file. But full disclosure, I'm no Ruby expert.

suchanlee

Thanks @aervin! Super stoked to get this in.

aervin · 2018-04-20T11:35:46Z

Thanks for your help @suchanlee 👍

suchanlee · 2018-04-20T17:46:12Z

Np!

aervin · 2018-05-03T14:30:32Z

@Shinigami92 You did a lot of great work updating the docs on your fork--any interest in opening a PR with those changes?

codeExample support init implementation

f6c7d8e

aervin changed the title ~~codeExample support init implementation~~ [docs] adds optional capability to provide code examples in rules' metadata Dec 21, 2017

aervin commented Dec 22, 2017

View reviewed changes

ajafff reviewed Dec 26, 2017

View reviewed changes

Aaron Ervin added 6 commits January 3, 2018 17:52

dedent/markdown errors need revisting

06a2954

updates to new code example scheme as per ajafff

658e593

reverts prettier style updates in curly

d075a5a

curly docs he -> they

938420c

ICodeExample config type any -> string

57c4188

Code example blocks now color-coded according to pass/fail (grn/red)

12bcc3a

updates to buildDocs

227ae45

aervin mentioned this pull request Mar 20, 2018

Add Examples For Rules #3776

Closed

suchanlee reviewed Apr 9, 2018

View reviewed changes

Aaron Ervin added 2 commits April 9, 2018 09:07

gemfile.lock??; removes unnecessary html/scss

5c78e6a

removes site dist

67a0eb1

JoshuaKGoldberg reviewed Apr 13, 2018

View reviewed changes

Aaron Ervin added 2 commits April 13, 2018 07:59

moving code examples to dedicated dir to avoid bloat in rule files

6ba33df

removing _site dir

b6fa661

suchanlee reviewed Apr 16, 2018

View reviewed changes

suchanlee approved these changes Apr 19, 2018

View reviewed changes

suchanlee merged commit 5c86dd4 into palantir:master Apr 19, 2018

aervin mentioned this pull request Apr 23, 2018

Add ban-ts-ignore rule. #3728

Merged

4 tasks

rafaelss95 mentioned this pull request May 5, 2018

Show code examples in site mgechev/codelyzer#606

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] adds optional capability to provide code examples in rules' metadata #3602

[docs] adds optional capability to provide code examples in rules' metadata #3602

aervin commented Dec 21, 2017

aervin Dec 22, 2017

ajafff Dec 26, 2017

aervin Dec 26, 2017 •

edited

Loading

aervin commented Jan 14, 2018

Shinigami92 commented Jan 14, 2018 •

edited

Loading

aervin commented Jan 14, 2018

Shinigami92 commented Jan 14, 2018

Shinigami92 commented Jan 14, 2018 •

edited

Loading

Shinigami92 commented Jan 14, 2018

Shinigami92 commented Jan 15, 2018 •

edited

Loading

aervin commented Jan 15, 2018

Shinigami92 commented Jan 15, 2018

aervin commented Jan 15, 2018

Shinigami92 commented Jan 15, 2018

aervin commented Jan 15, 2018

aervin commented Apr 8, 2018

suchanlee commented Apr 9, 2018

suchanlee Apr 9, 2018

aervin Apr 9, 2018

suchanlee Apr 9, 2018

suchanlee Apr 9, 2018

aervin Apr 9, 2018

suchanlee Apr 9, 2018

suchanlee Apr 9, 2018

suchanlee commented Apr 9, 2018 •

edited

Loading

aervin commented Apr 9, 2018

JoshuaKGoldberg Apr 13, 2018

aervin Apr 13, 2018

suchanlee Apr 16, 2018

aervin Apr 16, 2018

suchanlee left a comment •

edited

Loading

aervin commented Apr 20, 2018

suchanlee commented Apr 20, 2018

aervin commented May 3, 2018

[docs] adds optional capability to provide code examples in rules' metadata #3602

[docs] adds optional capability to provide code examples in rules' metadata #3602

Conversation

aervin commented Dec 21, 2017

PR checklist

Overview of change:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aervin Dec 26, 2017 • edited Loading

Choose a reason for hiding this comment

aervin commented Jan 14, 2018

Shinigami92 commented Jan 14, 2018 • edited Loading

aervin commented Jan 14, 2018

Shinigami92 commented Jan 14, 2018

Shinigami92 commented Jan 14, 2018 • edited Loading

Shinigami92 commented Jan 14, 2018

Shinigami92 commented Jan 15, 2018 • edited Loading

aervin commented Jan 15, 2018

Shinigami92 commented Jan 15, 2018

aervin commented Jan 15, 2018

Shinigami92 commented Jan 15, 2018

aervin commented Jan 15, 2018

aervin commented Apr 8, 2018

suchanlee commented Apr 9, 2018

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

suchanlee commented Apr 9, 2018 • edited Loading

aervin commented Apr 9, 2018

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

suchanlee left a comment • edited Loading

Choose a reason for hiding this comment

aervin commented Apr 20, 2018

suchanlee commented Apr 20, 2018

aervin commented May 3, 2018

aervin Dec 26, 2017 •

edited

Loading

Shinigami92 commented Jan 14, 2018 •

edited

Loading

Shinigami92 commented Jan 14, 2018 •

edited

Loading

Shinigami92 commented Jan 15, 2018 •

edited

Loading

suchanlee commented Apr 9, 2018 •

edited

Loading

suchanlee left a comment •

edited

Loading