Dev tooling 31 - adds an 'includeShared' mixin for sharing jade snippets.

[jtraband]

adds an 'includeShared' mixin for sharing jade snippets.

[googlebot]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed, please reply here (e.g. I signed it!) and we'll verify. Thanks.

---

• If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
• If you signed the CLA as a corporation, please let us know the company's name.

[googlebot]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed, please reply here (e.g. I signed it!) and we'll verify. Thanks.

---

• If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
• If you signed the CLA as a corporation, please let us know the company's name.

[filipesilva]

Would this allow an author to have a jade dcument that pulls in parts from other jade documents?

[jtraband]

Exactly!

Markup consists of a jade file follows the same #docregion #enddocregion conventions as elsewhere. The comment delimiter for jade files is a ‘//’.

So in your jade file simply add something like:

// #docregion foo
… jade content
// #enddocregion

All of the capabilities of nested and combined regions are supported here just like elsewhere.

To consume the shared section use the ‘includeShared’ mixin. It takes two arguments:

+includeShared(filePath, region)

So you could use it from a js jade doc to point to a section in the ts file in the ts folder with something like this.

+includeShared(‘../../ts/xxx.jade’, ‘foo’)

But because I am assuming that you are going to be sharing with similarly named files across directories there is a shortcut for this. i.e. a/b/ts/xx/yy/aaa.jade will be used by a/b/js/xx/yy/aaa.js

+includeShared(‘{ts}’, foo)

The ‘{ts}’ is a shorthand to go up and over and down to the same file in the ‘ts’ subfolder. Similarly if you wanted to point to a js file from a ts file you would use ‘{js}’.

Side note: Not needed to use the tool, but be aware that ‘shredding’ jade files does not use the fragments folder but instead shreds in place in the source folder and creates files that begin with ‘_.’

[filipesilva]

Amazing work Jay! This will surely help in producing a shared infrastructure for producing chapters in TS/JS/Dart.

[wardbell]

Huge payoff!

Here is what the jade looks like (or would look like if we had the JS versions of the doc pages that are linked in the original) for the Developers Guide home page:

include ../../../../_includes/_util-fns
+includeShared('{ts}', 's1')
:marked
  Look for a link to a running version of that sample near the top of each page such as this
  [live example](/resources/live-examples/architecture/js/plnkr.html) from the [Architecture](architecture.html) chapter.
+includeShared('{ts}', 's2')
:marked

It required exactly TWO // #docregion markups, named 's1' and 's2'

[wardbell]

Merged by 45ac0ee