Commit Graph

343 Commits

Author SHA1 Message Date
Pete Bacon Darwin f440bd1793 build(docs-infra): fix CLI command github links ()
The "view" links were broken because the version used to
compute the git tag for the GitHub URL included a build SHA.
Now we clean that off before using it in the URL.

The links are to the JSON schema that defines the documentation for
the command. This is accurate but confusing because the content for the
long description is stored in a separate markdown file referenced from this
schema file.
This commit adds a second set of links for the long description, if it exists,
which links directly to the markdown file.

Closes 

PR Close 
2019-06-06 08:49:37 -07:00
Brandon 6debe9dfb9 docs(docs-infra): add common/upgrade to authors package for API docs ()
This fixes an issue where the common/upgrade packge isn't included
on page reload when changes are made to the common/upgrade package

PR Close 
2019-05-21 13:09:09 -07:00
Ben Lesh d7eaae6f22 refactor(ivy): Move instructions back to ɵɵ ()
There is an encoding issue with using delta `Δ`, where the browser will attempt to detect the file encoding if the character set is not explicitly declared on a `<script/>` tag, and Chrome will find the `Δ` character and decide it is window-1252 encoding, which misinterprets the `Δ` character to be some other character that is not a valid JS identifier character

So back to the frog eyes we go.

```
    __
   /ɵɵ\
  ( -- ) - I am ineffable. I am forever.
 _/    \_
/  \  /  \
==  ==  ==
```

PR Close 
2019-05-20 16:37:47 -07:00
jenniferfell 1c3ee41902 docs: move old quick start content into new local setup guide ()
PR Close 
2019-05-20 10:16:23 -07:00
Brandon 6cb3b50a03 docs(docs-infra): add common/upgrade to API package sources ()
Closes 

PR Close 
2019-05-16 11:47:16 -07:00
Ben Lesh cf86ed7b29 refactor(ivy): migrate ɵɵ prefix back to Δ ()
Now that issues are resolved with Closure compiler, we can move back to our desired prefix of `Δ`.

PR Close 
2019-05-14 16:52:15 -07:00
George Kalpakas d80ae6ba0d build(docs-infra): ensure hidden cli commands are excluded from `sitemap.xml` ()
Previously, the processor that excludes certain cli commands
(`filterHiddenCommand`) was being run after the `createSitemap`
processor, resulting in those commands to be present in `sitemap.xml`,
while the actual pages where missing. This also resulted in 404s, when
search engine crawlers tried to index the missing URLs.

This commit fixes it by ensuring that the `filterHiddenCommand`
processor is run before the `createSitemap` processor.

PR Close 
2019-05-10 11:56:39 -07:00
Alex Rickabaugh b0578061ce refactor(ivy): use ɵɵ instead of Δ for now ()
The `Δ` caused issue with other infrastructure, and we are temporarily
changing it to `ɵɵ`.

This commit also patches ts_api_guardian_test and AIO to understand `ɵɵ`.

PR Close 
2019-04-11 16:27:56 -07:00
Ben Lesh 138ca5a246 refactor(ivy): prefix all generated instructions ()
- Updates all instructions to be prefixed with the Greek delta symbol

PR Close 
2019-04-10 12:11:40 -07:00
George Kalpakas 8bbf481d60 refactor(docs-infra): rename properties (blacklisted --> ignored) ()
PR Close 
2019-04-08 09:46:34 -07:00
George Kalpakas c5bba8d9f2 build(docs-infra): do not include `announcements.json` in sitemap ()
The `announcements.json` file should not be included in the sitemap and
including it causes an error in Google Search Console (because the
generated URL does not exist).

(This is a follow-up to fbef94a8e.)

PR Close 
2019-04-08 09:46:33 -07:00
Pete Bacon Darwin 433b7b02a4 test(docs-infra): fix eslint warnings ()
```
warning  An "it" that uses an async method should handle failure (use "done.fail")  jasmine/no-promise-without-done-fail
```

PR Close 
2019-04-04 10:52:36 -07:00
Pete Bacon Darwin a4f3f3f81d build(docs-infra): support doc aliases via `@alias` dgeni tag ()
Now, one can add an `@alias` tag to API docs, which tells dgeni that this
API element (usually a `const`) is really just an alias for some API element
defined elsewhere.

Dgeni will then look up this API element and copy over the properties from
the alias to the current doc.

For example, we would like to privately export an Enum from `@angular/core`
but then publicly export this from `@angular/common`:

**packages/core/private_exports.ts**

```ts
/**
 * Description of this document.
 */
export enum ɵSomeEnum { ... }
```

**packages/common/public_api.ts**

```ts
import {ɵSomeEnum} from '@angular/core';

 /**
 * @alias core/ɵSomeEnum
 */
export const SomeEnum = ɵSomeEnum;
```

In the generated docs there will be a page for `common/SomeEnum`, which
will be rendered as an enum, rather than a const, showing the description
extracted from the `core/ɵSomeEnum`.

---

The implementation of this feature required some refactoring of the other
processing:

1. Previously `ɵ` prefixed exports were not even considered.
2. Due to 1. some processors needed to have guards added to ignore such
   private exports (`addMetadataAliases` and `checkContentRules`).
3. The processing of package pages had to be reworked (and split) so that
   it picked up the aliased export docs after their alias proeprties had
   been copied.

See FW-1207, FW-632, 

PR Close 
2019-04-04 10:52:36 -07:00
Pete Bacon Darwin 6233cd55f7 style(docs-infra): fix typo ()
PR Close 
2019-04-04 10:52:36 -07:00
Alex Eagle 03d914a6c2 build: hide @angular/http for Angular v8 ()
Currently our plan is to skip the publish, docgen, and update steps for this package.
During RC, we'll determine if the breaking change is too difficult for users, in which case we might restore the package for another major.

PR Close 
2019-04-02 10:55:31 -07:00
Brandon 12c9bd257d docs: add new getting started guide ()
PR Close 
2019-03-29 10:47:37 -07:00
Adam Plumer 6b6fdffc12 fixup! docs: update Universal guide ()
PR Close 
2019-03-11 10:52:18 -07:00
Adam Plumer a29ce57732 docs: migrate examples from @angular/http to @angular/common/http ()
PR Close 
2019-03-11 10:52:17 -07:00
Alan Agius d940b5541f fix(docs-infra): boolean options default value is incorrect when it's undefined ()
In the CLI when it's undefined it can mean `false`, or sometimes it will be overwritten by a runtime value.

PR Close 
2019-01-28 20:43:15 -08:00
WilliamKoza e2c98fbe11 fix(docs-infra): change the key used to find out the cli section ()
PR Close 
2019-01-24 15:41:44 -08:00
WilliamKoza 4c0104c846 fix(docs-infra): Add crossed through styling ()
PR Close 
2019-01-14 10:45:46 -08:00
WilliamKoza 72f2428cd8 fix(docs-infra): change style of `deprecated` markers ()
PR Close 
2019-01-14 10:45:46 -08:00
WilliamKoza d577b8df75 fix(docs-infra): render `deprecated` markers for CLI command options ()
fixes 
fixes 

PR Close 
2019-01-14 10:45:46 -08:00
Pete Bacon Darwin cd51775390 build(docs-infra): render `@see` information in members ()
Previously `@see` tags were only rendered for top level class-like
docs. Now these tags are rendered for methods and properties too.

PR Close 
2019-01-11 14:35:23 -08:00
Pete Bacon Darwin 18b6d580c5 fix(docs-infra): update overload rendering ()
Based on the review here:
https://github.com/angular/angular/pull/24976#issuecomment-415535125

PR Close 
2018-11-01 14:17:11 -07:00
Pete Bacon Darwin 03417df54e build(docs-infra): display long overload parameter types as `object` ()
In some overloads, the parameter type can be a large anonymous
object type.
This change displays such types as `object`. It is then up to the
documentation author to put more information about the type in the
method usage notes.

PR Close 
2018-11-01 14:17:11 -07:00
Pete Bacon Darwin 61cd5f7c0f build(docs-infra): fix individual API overload templates ()
* Make individual overloads collapsible
* Show only the first overload expanded, rest collapsed
* Text changes to 'collapse all' once 'show all' is clicked
* Fix chevron/carrot rotation animation when overloads / overload item is expanded or collapsed

PR Close 
2018-11-01 14:17:11 -07:00
Pete Bacon Darwin 68dfa04f8a build(docs-infra): add method overload index ()
PR Close 
2018-11-01 14:17:10 -07:00
Stefanie Fluin 6902977665 build(docs-infra): improve API overload templates ()
PR Close 
2018-11-01 14:17:10 -07:00
Pete Bacon Darwin d72d50d83e build(docs-infra): move CLI API desciption higher up ()
Closes 

PR Close 
2018-10-29 13:01:08 -04:00
Pete Bacon Darwin 07509da78d build(docs-infra): ensure that CLI code blocks are not auto-linked ()
Some of the text in CLI API docs were being auto-linked to API
pages. This was not correct, and in fact these blocks should not
have any auto links to Angular API at all.

Closes 

PR Close 
2018-10-26 18:09:20 -04:00
Pete Bacon Darwin 9ff8155cd9 build(docs-infra): mark code blocks to disable auto-linking ()
You can now mark `<code>` blocks with a `no-auto-link` css class
to tell the code auto-linker to ignore this code block.

PR Close 
2018-10-26 18:09:20 -04:00
Pete Bacon Darwin 7c730fe5b3 build(docs-infra): include inherited members in search index ()
Closes 

PR Close 
2018-10-26 13:16:33 -04:00
Pete Bacon Darwin f233131974 build(docs-infra): refactor generateKeywords processor ()
PR Close 
2018-10-26 13:16:32 -04:00
Pete Bacon Darwin 4bd9f53e8f feat(docs-infra): rename tagdef: `@experimental` to `@publicApi` ()
PR Close 
2018-10-19 14:35:52 -07:00
Pete Bacon Darwin 4c0ad5238e build(docs-infra): display github links in CLI API docs ()
This commit includes the following changes:

* CLI version information is read from the CLI package from which
  we read the help files.
* CLI API pages now contain GH links
* line numbers are not shown in GH links, if the doc does not
  have a truthy `startingLine` value. This allows us to remove
  hard coded checks for `guide` pages
* content pages and CLI api docs no longer have a `startingLine`
* the hard-coded `packages` path segment has been removed from
  the templates; instead we now only use the `realProjectRelativePath`.
* the `realProjectRelativePath` has been updated accordingly for API
  and CLI API docs.

PR Close 
2018-10-19 11:12:54 -07:00
Pete Bacon Darwin 9e8903ada1 build(docs-infra): show github edit link on CLI overview ()
PR Close 
2018-10-19 11:12:53 -07:00
Pete Bacon Darwin b9bd95b3b2 build(docs-infra): break long CLI options onto two lines ()
PR Close 
2018-10-19 11:07:30 -07:00
Pete Bacon Darwin 3f89aeb80a build(docs-infra): update CLI option rendering ()
PR Close 
2018-10-19 11:07:30 -07:00
Pete Bacon Darwin 6c530d3a85 build(docs-infra): render CLI arguments consistently ()
In the command syntax, arguments are rendered as
`var`s enclosed in angle brackets. So this is now repeated
in the arguments table too.

PR Close 
2018-10-19 11:07:30 -07:00
George Kalpakas d9d226087c build(docs-infra): allow `""` as empty region in `{@example}` tags ()
PR Close 
2018-10-18 09:54:17 -07:00
George Kalpakas 7bad1d356d build(docs-infra): only render code example content in one place ()
PR Close 
2018-10-18 09:54:17 -07:00
George Kalpakas 0add00a743 build(docs-infra): throw error if using `title` on code snippets ()
Since , the `title` property is ignored and `header` should be
used instead for specifying a code snippet's header.

This commit ensures that we don't accidentally set `title` have it be
silently ignored.

PR Close 
2018-10-18 09:54:17 -07:00
William Marques fc6dad40ac fix(docs-infra): rename "title" by "header" to avoid unwanted tooltips ()
Closes 

PR Close 
2018-10-17 11:05:29 -07:00
Pete Bacon Darwin ea20ae63d0 build(docs-infra): only show name in 'inherited from' section ()
Closes 

PR Close 
2018-10-12 09:13:02 -07:00
George Kalpakas 67608a907e build(docs-infra): make the git ref for cli command docs configurable ()
PR Close 
2018-10-11 12:57:49 -07:00
Pete Bacon Darwin 5977b72e9c build(docs-infra): fix formatting of entry point export table ()
Now that `list-table` cells are `pre` formatterd we must be careful
of what whitespace appears in text nodes.

PR Close 
2018-10-01 09:36:34 -07:00
Pete Bacon Darwin 7373da9b11 build(docs-infra): simplify property syntax rendering ()
PR Close 
2018-10-01 09:36:34 -07:00
Pete Bacon Darwin 783a682a7d build(docs-infra): remove unused property table heading ()
PR Close 
2018-10-01 09:36:34 -07:00
Pete Bacon Darwin d22418d417 build(docs-infra): add short description "See more" link ()
If there is additional (non-short) description then add in a
link to the short description to take the reader there.

PR Close 
2018-10-01 09:36:34 -07:00
Pete Bacon Darwin 4b1fd98093 build(docs-infra): pluralize NgModule(s) heading as appropriate ()
PR Close 
2018-10-01 09:36:34 -07:00
Pete Bacon Darwin 935ef13096 build(docs-infra): improve directive selector rendering ()
`:not(...)` blocks are now rendered as italic, while the
rest of the selector is bold.

PR Close 
2018-10-01 09:36:33 -07:00
Pete Bacon Darwin f4b60588fb build(docs-infra): move directive macros into memberHelpers.html ()
PR Close 
2018-10-01 09:36:33 -07:00
Pete Bacon Darwin 15dadb92ef build(docs-infra): include directives etc in class descendants lists ()
PR Close 
2018-10-01 09:36:33 -07:00
Pete Bacon Darwin ce06a75ebf build(docs-infra): display inherited members on directives ()
PR Close 
2018-10-01 09:36:33 -07:00
Pete Bacon Darwin 9889276b15 build(docs-infra): directive inputs and outputs ()
PR Close 
2018-10-01 09:36:33 -07:00
Pete Bacon Darwin d0f7eadc09 build(docs-infra): rename example template variable in directive pages ()
PR Close 
2018-10-01 09:36:33 -07:00
Pete Bacon Darwin 4b132c9848 build(docs-infra): remove class overview from directive pages ()
PR Close 
2018-10-01 09:36:33 -07:00
Pete Bacon Darwin 46729c76a0 build(docs-infra): improve directive selector rendering ()
If the documentation contains a `@selectors` tag then the content of that
is used to describe the selectors of a directive.

Otherwise the selector string is split and each selector is listed as
a list item in an unordered list.

PR Close 
2018-10-01 09:36:33 -07:00
Pete Bacon Darwin f22deb2e2d build(docs-infra): improve directive API doc templates ()
Closes 
Closes 

PR Close 
2018-10-01 09:36:32 -07:00
Pete Bacon Darwin f29b218060 feat(docs-infra): generate Angular CLI command reference ()
PR Close 
2018-09-26 11:24:02 -07:00
Pete Bacon Darwin b8422b41bb build(docs-infra): fail doc-gen if a content rule fails ()
PR Close 
2018-09-24 09:11:02 -07:00
Pete Bacon Darwin 8ac4dd6447 build(docs-infra): allow usage notes on decorator option properties ()
PR Close 
2018-09-24 09:11:02 -07:00
Pete Bacon Darwin 3808416479 build(docs-infra): remove legacy jsdoc tag processing ()
PR Close 
2018-09-24 09:11:02 -07:00
Pete Bacon Darwin cee7448efc build(docs-infra): add @nocollapse tag-def to prevent warning ()
See https://github.com/angular/angular/blob/master/packages/compiler-cli/src/transformers/nocollapse_hack.ts

PR Close 
2018-09-24 09:11:02 -07:00
Pete Bacon Darwin 7f1cace2a2 build(docs-infra): sort NgModule exports by id ()
PR Close 
2018-09-21 17:00:03 -07:00
Pete Bacon Darwin 56c86c7e79 build(docs-infra): sort package exports by id ()
Closes 

PR Close 
2018-09-21 17:00:03 -07:00
Pete Bacon Darwin 026b60cd70 build(docs-infra): expose deprecated status on items more clearly ()
PR Close 
2018-09-21 10:26:48 -07:00
Pete Bacon Darwin cea2e0477c fix(docs-infra): render security risk labels ()
PR Close 
2018-09-21 10:26:48 -07:00
Pete Bacon Darwin 96f9f03d25 build(docs-infra): improve search quality ()
PR Close 
2018-09-21 10:26:48 -07:00
Pete Bacon Darwin 9931bd7576 build(docs-infra): do not include license comment in first API doc ()
The default dgeni config is to concatenate leading comments in front of API items.

In the case that you have an API item that starts a file with no import statements,
the license comment at the top of the file was being added to the front of the
API item's comment. SInce the license comment includes the `@license` tag
and the API item's comment did not start with `@description` the content of
the API item's comment was being put inside the `@license` tag, and no
description was being extracted from the API item's comment.

This commit updates to a version of dgeni-packages that has a switch to turn off
this concatenation, and then also configures this switch.

Closes 

PR Close 
2018-09-21 10:25:41 -07:00
Pete Bacon Darwin b94436d86c build(docs-infra): process and render ngmodule exports ()
All directives and pipes must now be tagged with one ore more
public NgModule, from which they are exported.

If an item is exported transitively via a re-exported internal NgModule
then it may be that the item appears to be exported from more than
one public NgModule. For example, there are shared directives that
are exported in this way from `FormsModule` and `ReactiveFormsModule`.

The doc-gen will error and fail if a directive or pipe is not tagged correctly.

NgModule pages now list all the directives and pipes that are exported from it.
Directive and Pipe pages now list any NgModule from which they are exported.
Packages also now list any NgModules that are contained - previously they were
missed.

PR Close 
2018-09-19 16:18:24 -07:00
Pete Bacon Darwin bc5cb8153e build(docs-infra): separate NgModules from Classes in API docs ()
PR Close 
2018-09-19 16:18:24 -07:00
Pete Bacon Darwin 34b848ad51 build(docs-infra): remove unused info-bar API template ()
PR Close 
2018-09-19 16:18:24 -07:00
Pete Bacon Darwin 4a04ab8823 build(docs-infra): do not render internals in package API pages ()
Closes 

PR Close 
2018-09-05 09:28:05 -07:00
Martin Sikora d539122466 refactor(docs-infra): refactor templates ()
PR Close 
2018-08-31 09:42:10 -07:00
Martin Sikora b89a7dd4a2 fix(docs-infra): show "suggest edits" only for /guide and /tutorial dirs ()
PR Close 
2018-08-31 09:42:10 -07:00
Martin Sikora 9533cc9809 feat(docs-infra): add "suggest edits" feature to all docs ()
PR Close 
2018-08-31 09:42:10 -07:00
Pete Bacon Darwin b1902db0cb build(docs-infra): render all overloads if they are abstract ()
In an overloaded method, the overload with the function body is the
actual method doc, and this doc is not included in the list of "additional"
overloads.

Moreover, the logic (all in dgeni-packages) is that if none of the items
has a body then we use the first overload as the actual method doc.

In the case of abstract methods, none of the methods have a body. So we
have a situation where the overloads collection does not contain the first
abstract method, even though it is not the "implementation" of the method.
Therefore we need to still render it.

Closes 

PR Close 
2018-08-27 18:19:08 -04:00
Pete Bacon Darwin a081d207f8 build(docs-infra): remove "annotations" section from API pages ()
PR Close 
2018-08-27 18:18:41 -04:00
Pete Bacon Darwin c13901f4c8 build(docs-infra): remove stability labels from API docs ()
PR Close 
2018-08-14 13:17:15 -07:00
Pete Bacon Darwin 6a2130117f build(docs-infra): clean up API package template ()
PR Close 
2018-08-14 13:17:15 -07:00
Pete Bacon Darwin 4e45f2c481 build(docs-infra): include packages in API template breadcrumbs ()
PR Close 
2018-08-14 13:17:15 -07:00
Pete Bacon Darwin 78f477652e build(docs-infra): change breadcrumb delimiter to `>` ()
PR Close 
2018-08-14 13:17:15 -07:00
Pete Bacon Darwin edef58f466 build(docs-infra): ensure all API headings are sentence cased ()
Closes 

PR Close 
2018-07-23 08:43:07 -07:00
George Kalpakas 3cd9645daa fix(docs-infra): fix table header layout in API pages ()
PR Close 
2018-07-20 10:48:42 -07:00
Pete Bacon Darwin d8c828c9b1 build(docs-infra): implement the 'package' API template ()
PR Close 
2018-07-13 19:45:54 -04:00
Pete Bacon Darwin d876700c26 build(docs-infra): render short description of parameters in API docs ()
PR Close 
2018-06-28 15:03:14 -07:00
Pete Bacon Darwin cf0968f98e build(docs-infra): support hiding constructors of injectable classes ()
Classes that are injectable often have constructors that should not be
called by the application developer. It is the responsibility of the
injector to instantiate the class and the constructor often contains
private implementation details that may need to change.

This commit removes constructors from the docs for API items that are
both:

a) Marked with an injectable decorator (e.g. Injectable, Directive,
Component, Pipe), and
b) Have no constructor description

This second rule allows the developer to override the removal if there
is something useful to say about the constructor.

Note that "normal" classes such as `angimations/HttpHeaders` do not have
their constructor removed, despite (at this time) having no description.

PR Close 
2018-06-26 10:58:11 -07:00
Pete Bacon Darwin 8c51ce6f3b build(docs-infra): move overload short description above syntax ()
PR Close 
2018-06-25 07:56:36 -07:00
Pete Bacon Darwin 45862d0812 build(docs-infra): ensure all headings are sentence cased ()
PR Close 
2018-06-15 09:13:45 -07:00
Pete Bacon Darwin 39af314e29 build(aio): add github links to API doc members ()
This change adds Github edit and view links to methods
and decorator options.

It is possible to add these to properties also but the
UI is rather tight as these are displayed in a table.

PR Close 
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin 8daadf360c build(aio): compute breadcrums for all API doc types ()
PR Close 
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin 859a3d5784 build(aio): fix decorator doc "inherited from" heading ()
We should not include the package path in the inherited
from heading for decorator API docs

PR Close 
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin 8a4c577917 build(aio): fix broken doc-gen unit test ()
PR Close 
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin 2b15108f7e build(aio): remove invalid H3 usage notes heading ()
This heading is too high for the section because the
method name is a H3 but it cannot be a H4 because
usage notes may contain H4 headings.

PR Close 
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin bc4f10ca20 build(aio): rearrange processors to ensure we catch all content errors ()
PR Close 
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin 77309e2ea4 build(aio): map H3 headings into H4 headings for certain templates ()
The sections such as methods and decorator options are already headed
by a H3 heading so we need to map the H3 headings in the API doc source
down to H4 headings.

This commit includes general heading mapping functionality accessible via
the `marked` Nunjucks filter.

PR Close 
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin e371b226fa build(aio): rearrange decorator API doc template ()
The overview of the decorator options is now a table.
The detailed description of each option is now a full section.

PR Close 
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin ccb19fea68 build(aio): remove unused `@linkDocs` alias for `@link` jsdoc tag ()
PR Close 
2018-06-13 16:47:40 -07:00