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
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
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
Do not match code "words" that are part of a hyphenated
string of characters: e.g. `platform-browser-dynamic` should
not auto-link `browser`.
Do not match code "words" that correspond to pipe names
but are not preceded by a pipe `|` character. E.g. `package.json` should
not auto link `json` to the `JsonPipe`.
Closes#20187
PR Close#20468
Using `display: none` on the `<h1>` causes `innerText` to not work as expected
and include the icon ligature (`link`) in the title. This caused the window
title on the angular.io Home page to appear as "Angular - link".
This commit fixes it by not generating anchors at all for headings with the
`no-anchor` class.
Fixes#20427
PR Close#20440
This PR was merged without API docs and general rollout plan.
We can't release this as is in 5.1 without a plan for documentation, cli integration, etc.
Checks that cause the doc-gen to fail were already disabled in `docs-watch`
for the doc-gen that runs when a file is changed.
Now these checks are also disabled for the initial doc-gen run.
closes#20038
By setting `renderExamples.ignoreBrokenExamples = true` the doc-gen will
not fail if there is something wrong with an example. Instead it will
just log a warning.
Upgrading to dgeni-packages 0.21.4 gives us
access to more properties on the API docs, which
allows us to fix the following issues:
Closes#19450Closes#19452Closes#19456
This change will enable people to link to the API docs via their selectors
or names, as used in a template.
Since the selectors can be quite complex we are not able to get 100%
accuracy.
Closes#16787
For classes, the tree of subclasses is rendered, recursively.
For interfaces, the descendants are separated into child interfaces, which
extend the interface, and classes, which implement the interface.
Closes#19306
The API docs have changed. The line numbers are now found in
`startingLine` and `endingLine` properties rather than the `location`
property, which moved into the `fileInfo` property anyway.
The API docs tests have very variable run times, depending
upon the build environment.
This change doubles their test timeout values to prevent
false-negative failures.
Rather than hard coding excludes into the dgeni config,
use the fact that we are already ignoring the boilerplate
and generated files via the .gitignore file.
* Remove whitespace before type specifiers
* Generate `new` and `call` member info for interfaces
* Ensure that there is no double space after class names
If a usage of `{@link ...}` does not provide a title then
compute it based on the `title` and/or `name` properties
or set the link to invalid.
Closes#16811
This fail behaviour is only turned on for `yarn docs`;
in `yarn docs-watch` you only receive a warning.
This is because you can get false errors when watching
since we don't parse all the docs in that case.
* fix(aio): allow code blocks to clear floated images
Previously the negative margin on the code headings were causing
floated images to overlay the start of a code block. Now all code block
successfully clear all floated elements.
* feat(aio): add a `.clear` class for clearing floating images
* fix(aio): tidy up image styles
The css rules for `img.right` and `img.left` allow authors easy
access to floating an image on the left or right, respectively.
The `.image-display` rule which was always found on a figure
has been simplified so that all figures have this styling. It is very
unlikely that a figure will be used outside the content area; and
at this time it seems like `figure` is as good an indicator that we
want this kind of styling as anything.
Now that images are all tagged with width and height values, we cannot
assume to modify these dimensions via CSS as it can cause the image to
lose its correct proportions. Until we find a better solition we must set
`height` to `auto` when the screen width is below 1300px to ensure that
these images maintain their proportions as they get shrunk to fit.
* docs(aio): general tidy up of image HTML in guides
Previously, the guides have a lot of inline image styling and unnecessary
use of the `image-display` css class.
Images over 700px are problematic for guide docs, so those have been given
specific widths and associated heights.
* docs(aio): use correct anchor for "back to the top" link
The `#toc` anchor does not work when the page is
wide enough that the TOC is floating to the side.
* build(aio): add `#top-of-page` to path variants for link checking
Since the `#top-of-page` is outside the rendered docs
the `checkAnchorLinks` processor doesn't find them
as valid targets for links.
Adding them as a `pathVariant` solves this problem
but will still catch links to docs that do not actually exist.
* fix(aio): ensure that headings clear floated images
* fix(aio): do not force live-example embedded image to 100% size
This made them look too big, generally. Leaving them with no size means
that they will look reasonable in large viewports and switch to 100% width
in narrow viewports.
- Moved info bar section in pipe template to be the first section to match other templates
- Fixed label styling for type label
- Added label styling for status label
Parse all `<img>` tags, during doc-gen, and insert the width and height of
the sourceed image, if neither are already specified.
Warnings are reported if the `<img>` tag has no `src` attribute or the image
cannot be loaded.
The work is done in the `addImageDimensions` post-processor, which must be
configured with a `basePath` so that it knows where to find the images.
Closes#15888
The autolinking is now done on the `renderedContent` which means it also
captures and autolinks headings that were generated outside of markdown.
PR Close#16336
- Banner class code consolidation for API pages
- Set up temporary table of contents class and file
- API pages title styling
- Add color styling to doc-type listed on each API details page
- Classes and SCSS variables refactor
- Mobile optimization on headers, info-banner, and API pages
- API page table custom styling
- API Class Overview template code overview into table format
We were filtering this document from the docs list but
not removing it from the module export lists.
We can actually filter it out much easier at the TypeScript
parsing point, which means we do not need the
`filterIgnoredDocs` processor any more.
Closes#16287
This is to tidy up the `author-packagse`, which currently duplicates a
lot of the configuration in the main packages. We need to
DRY this up so that we don't fall foul of a change in one being missed in
the other.
Changed description from h3 to h2 to match the other header
Created api page classes for consistent styling
Add styles for info-bar section
Wrapped pre tags for code not to go off of screen
This helps to ensure that the full docs have been
generated before we begin watching.
You can disable this by providing the `--watch-only`
flag. E.g. `yarn docs-watch -- --watch-only`.
Now if you specifically provide an empty `@title` tag
for a contents file, the doc-gen will not complain and
the browser will just display a reasonable default.
If a document provided a title jsdoc tag then its h1
element was being rendered incorrectly as a markdown
paragraph.
This change renders the title as a markdown h1 tag
directly.
Fixes#16099
Documents can specify their title via the `title` or `name` jsdoc tags.
This change adds that, if neither are provided, the first `<h1>` element
is removed from the `renderedContent` and used for the title.
If there is still no title then it is set to the empty string and a warning
is logged.
Pete Bacon Darwin
Veres Lajos
Andrew Seguin
Alex Eagle
George Kalpakas
Jesus Rodriguez
Jason Aden
Igor Minar
Alex Rickabaugh
WilliamKoza
Suguru Inatomi
Victor Berchet
Stefanie Fluin
Ward Bell