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#26515
Since #26396, 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#26514
This commit also removes the extra jasminewd2 typings, since the changes
have been merged in the official typings with
DefinitelyTyped/DefinitelyTyped#28957.
PR Close#26139
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#25768
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#26045
PR Close#26050
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#25734
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#25610
PR Close#25670
It seems that occasionally the sharding of docs examples e2e tests gets
messed up resulting in some tests not being run. This can cause CI to be
green on a PR, when they shouldn't (because the failing tests didn't run
at all).
It is unclear under what circumstances this happens, so printing the
paths of found e2e specs will help debug the issue when it comes up
again.
PR Close#25293
Examples using `@angular/elements` need to transpile to es2015 for
Custom Elements to work (on browsers that natively support them).
Alternatively, a polyfill would need to be loaded. For now, changing the
transpilation target to es2015 is the simplest solution.
PR Close#24840
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#24529
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#24000
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#24000
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#24000
This commit adds new link disambiguators that mean that more
code links can be generated automatically in a sensible way.
The best example is the use of properties within class, interface and
enum documentation.
PR Close#24000
We don't really care when this processor runs as long as it happens
after the tags have been extracted.
By not constraining its `runBefore` property we can ensure that other
processors can be run before it.
PR Close#24000
Because we were "ignoring" these tags they were being
rendered as part of the previous tag.
What we really want to do is know about them, so that we
don't break the doc-gen but then ignore them when rendering.
PR Close#24000
Previously the API list was being generated before the stability had
been computed. This meant that the API list page showed no API docs
when filtering by `stable` stability status.
Closes#24329
PR Close#24356
Previously only the `description` and `usageNotes` were being copied over
from the call-member of the decorator interface. Important properties such
as `shortDescription` were missed.
These are now added and the code has been refactored to make it simpler and
clearer to update which properties get copied as the requirements change.
PR Close#24289
* The member details section is now called "Members", rather
than "Properties".
* The property table now displays appropriate table headings:
"Member", "Value", "Description".
* The "Value" column is not shown if none of the members have
a value.
Closes#22678
PR Close#23872
Previously these docs always displayed `any` as the type
of the const export. Now the type is computed correctly from
the declared type or initializer of the constant.
PR Close#23850
This processor will enable us to write rules about
how the content should appear, such as:
* no headings in markdown content
* only one sentence per line
* no single character parameter names
* etc.
PR Close#22759
It was running too late and so was being confused by the
description being split into `shortDescription` and `description`
properties.
Closes#22748
PR Close#22770
This change adds:
* an impure badge for Pipes that are marked as `pure: false`
* a pipe specific overview that shows the syntax for using a pipe in a template.
* an "input value" section describing the type of the value that the pipe expects.
* a "pipe params" section describing any additional params that a pipe expects.
PR Close#22702
We now create npm packages to cover all the public api assertions in tools/public_api_guard.
We no longer depend on ts-api-guardian from npm - it is now stale since the repository was archived.
There is no longer a gulp task to enforce or accept the public API, this is in CircleCI as part of running all bazel test targets.
PR Close#22639
Previously only export docs were displaying a short description.
Now methods in classes and interfaces also compute and render
the short description.
Closes#22500
PR Close#22583
The new version of `dgeni-packages/typescript` no longer strips
out "namespaces" from types, which was part of the problem of
not autolinking correctly to `HttpEventType.Response`.
Another part of the problem was that we did not include `.`
characters when matching potential code blocks for auto-linking,
which precluded properties of enums from being linked.
Finally, members we not being given a `path` property, which is
needed to effectively autolink to them. This is now set in
the `simplifyMemberAnchors` processor.
Closes#21375
PR Close#22494
The `exampleMap` needs to hold an hash object for each
of the `collectExamples.exampleFolders` paths.
Previously these hash objects were only created if there
was actually an example file the hash's respective
example folder. This could cause crashes during
`yarn docs-watch` (and so also `yarn sync-and-serve`)
if no examples were read in for a particular run of
the doc-gen.
PR Close#22502
* The first paragraph is now split off into the `shortDescription` property.
* Usage of `howToUse` and `whatItDoes` have been updated.
* The "Overview" heading for class is removed as it is self-evident
* The original horizontal rule styling below the main heading is removed as not part of the new design
Closes#22385
PR Close#22401
This approach simplifies the styling needed considerably.
Previously, we had to make room on the left for heading that
are in visual containers. Also we had to apply a `float:right`
when on narrow screens as the gutter not available then.
This float didn't render nicely if the heading text was longer
than could be rendered on a single line.
Closes#22131
This also prevents some extra `<a>` elements inserted by the browser's
trying to fix the HTML structure, which also fixes the `.header-link`
added in ToC.
Fixes#22387Closes#22437
PR Close#22446
- updates tests
- heavy prose revisions
- uses HttpClient (with angular-in-memory-web-api)
- test HeroService using `HttpClientTestingModule`
- scrub away most By.CSS
- fake async observable with `asyncData()`
- extensive Twain work
- different take on retryWhen
- remove app barrels (& systemjs.extras) which troubled plunker/systemjs
- add dummy export const to hero.ts (plunkr/systemjs fails w/o it)
- shrink and re-organize TOC
- add marble testing package and tests
- demonstrate the "no beforeEach()" test coding style
- add section on Http service testing
- prepare for stackblitz
- confirm works in plunker except excluded marble test
- add tests for avoidFile class feature of CodeExampleComponent
PR Close#20697
Now the overview groups the members in the following order:
* static properties
* static methods
* constructor
* instance properties
* instance members
Closes#22132
PR Close#22438
Includes:
* display ToC for API docs
* update dgeni-packages to 0.24.1
* add floating sidebar in API docs
* add breadcrumbs and structured data for Google crawler
* improved rendering of method overloads
* properties rendered in a table
* params rendered with docs
* removal of outdated "infobox" from all API docs
PR Close#21874
Previously searching for `compose` did not include `Validators`
in the search results because we were not including all the
`static` members of API docs in the index.
PR Close#21988
This has two benefits:
* it prepares the way for the API docs update, which need parameter docs
* it doesn't incorrectly report dangling links for non-latin anchors
Closes#21306
PR Close#21802
Also, remove `plnkr.json` for `service-worker-getting-started` guide,
since it is not used and ServiceWorker cannot work correctly in
plnkr/stackblitz anyway (e.g. no build step to re-compute hashes).
A zipper might be useful and can be added in a subsequent PR, but it is
currently broken (e.g. no dependency on `@angular/service-worker`).
PR Close#20165
- Update tooling to support revised testing guide (PR #20697).
- Require jasmine upgrade for examples that use marble testing.
- Copy `cli/package.json` to `testing/` and add `jasmine-marbles`.
- Resolve merge conflicts created by `NgModules` guides.
PR Close#20165
Previously the generated files were cleaned out before
doc-gen began (via a yarn pre-script). This can cause a
race condition in the CLI server, which prevents the new
generated files from being picked up.
Now we delay the cleaning until the last minute to ensure
that they ar still picked up by the webpack server.
PR Close#21540
The `@internal` tag prevents code items from appearing in the docs and the
typings files. You can now use `@nodoc` if you only want it to be excluded
from the docs and not the typings files.
Closes#20990
PR Close#21024
Since our version of Chromium is also pinned, a new ChromeDriver (that
drops support for our Chromium version) can cause random (and unrelated
to the corresponding changes) errors on CI.
This commit pins the version of ChromeDriver and it should now be
manually upgraded to a vrsion that is compatible with th currently used
Chromium version.
PR Close#20940
Fixes app build error in testing guide which has testing folder at multiple levels,
with files in them referring to files in the root `testing` folder.
Also removed the exclusion of files with `.1` in the name because
all app `.ts` files must be buildable per aio policy.
must build
PR Close#20779
Pete Bacon Darwin
George Kalpakas
William Marques
Brandon Roberts
Ben Lesh
Alex Eagle
Martin Sikora
Jan De Wilde
thebyteman
Brandon Roberts
Igor Minar
JiaLi.Passion
Veres Lajos
Andrew Seguin
Ward Bell
Jesus Rodriguez
Miško Hevery
Olivier Combe
Siyao Li
Jason Aden
Kapunahele Wong
Karthik Kumar A