build(aio): refactor dgeni packages
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.
This commit is contained in:
Peter Bacon Darwin
committed by
Pete Bacon Darwin
Pete Bacon Darwin
parent
7a8bd99ab1
commit
3cad5da5a4
@ -1,701 +0,0 @@
|
||||
a
|
||||
able
|
||||
about
|
||||
above
|
||||
abst
|
||||
accordance
|
||||
according
|
||||
accordingly
|
||||
across
|
||||
act
|
||||
actually
|
||||
added
|
||||
adj
|
||||
adopted
|
||||
affected
|
||||
affecting
|
||||
affects
|
||||
after
|
||||
afterwards
|
||||
again
|
||||
against
|
||||
ah
|
||||
all
|
||||
almost
|
||||
alone
|
||||
along
|
||||
already
|
||||
also
|
||||
although
|
||||
always
|
||||
am
|
||||
among
|
||||
amongst
|
||||
an
|
||||
and
|
||||
announce
|
||||
another
|
||||
any
|
||||
anybody
|
||||
anyhow
|
||||
anymore
|
||||
anyone
|
||||
anything
|
||||
anyway
|
||||
anyways
|
||||
anywhere
|
||||
apparently
|
||||
approximately
|
||||
are
|
||||
aren
|
||||
arent
|
||||
arise
|
||||
around
|
||||
as
|
||||
aside
|
||||
ask
|
||||
asking
|
||||
at
|
||||
auth
|
||||
available
|
||||
away
|
||||
awfully
|
||||
b
|
||||
back
|
||||
be
|
||||
became
|
||||
because
|
||||
become
|
||||
becomes
|
||||
becoming
|
||||
been
|
||||
before
|
||||
beforehand
|
||||
begin
|
||||
beginning
|
||||
beginnings
|
||||
begins
|
||||
behind
|
||||
being
|
||||
believe
|
||||
below
|
||||
beside
|
||||
besides
|
||||
between
|
||||
beyond
|
||||
biol
|
||||
both
|
||||
brief
|
||||
briefly
|
||||
but
|
||||
by
|
||||
c
|
||||
ca
|
||||
came
|
||||
can
|
||||
cannot
|
||||
can't
|
||||
cant
|
||||
cause
|
||||
causes
|
||||
certain
|
||||
certainly
|
||||
co
|
||||
com
|
||||
come
|
||||
comes
|
||||
contain
|
||||
containing
|
||||
contains
|
||||
could
|
||||
couldnt
|
||||
d
|
||||
date
|
||||
did
|
||||
didn't
|
||||
didnt
|
||||
different
|
||||
do
|
||||
does
|
||||
doesn't
|
||||
doesnt
|
||||
doing
|
||||
done
|
||||
don't
|
||||
dont
|
||||
down
|
||||
downwards
|
||||
due
|
||||
during
|
||||
e
|
||||
each
|
||||
ed
|
||||
edu
|
||||
effect
|
||||
eg
|
||||
eight
|
||||
eighty
|
||||
either
|
||||
else
|
||||
elsewhere
|
||||
end
|
||||
ending
|
||||
enough
|
||||
especially
|
||||
et
|
||||
et-al
|
||||
etc
|
||||
even
|
||||
ever
|
||||
every
|
||||
everybody
|
||||
everyone
|
||||
everything
|
||||
everywhere
|
||||
ex
|
||||
except
|
||||
f
|
||||
far
|
||||
few
|
||||
ff
|
||||
fifth
|
||||
first
|
||||
five
|
||||
fix
|
||||
followed
|
||||
following
|
||||
follows
|
||||
for
|
||||
former
|
||||
formerly
|
||||
forth
|
||||
found
|
||||
four
|
||||
from
|
||||
further
|
||||
furthermore
|
||||
g
|
||||
gave
|
||||
get
|
||||
gets
|
||||
getting
|
||||
give
|
||||
given
|
||||
gives
|
||||
giving
|
||||
go
|
||||
goes
|
||||
gone
|
||||
got
|
||||
gotten
|
||||
h
|
||||
had
|
||||
happens
|
||||
hardly
|
||||
has
|
||||
hasn't
|
||||
hasnt
|
||||
have
|
||||
haven't
|
||||
havent
|
||||
having
|
||||
he
|
||||
hed
|
||||
hence
|
||||
her
|
||||
here
|
||||
hereafter
|
||||
hereby
|
||||
herein
|
||||
heres
|
||||
hereupon
|
||||
hers
|
||||
herself
|
||||
hes
|
||||
hi
|
||||
hid
|
||||
him
|
||||
himself
|
||||
his
|
||||
hither
|
||||
home
|
||||
how
|
||||
howbeit
|
||||
however
|
||||
hundred
|
||||
i
|
||||
id
|
||||
ie
|
||||
if
|
||||
i'll
|
||||
ill
|
||||
im
|
||||
immediate
|
||||
immediately
|
||||
importance
|
||||
important
|
||||
in
|
||||
inc
|
||||
indeed
|
||||
index
|
||||
information
|
||||
instead
|
||||
into
|
||||
invention
|
||||
inward
|
||||
is
|
||||
isn't
|
||||
isnt
|
||||
it
|
||||
itd
|
||||
it'll
|
||||
itll
|
||||
its
|
||||
itself
|
||||
i've
|
||||
ive
|
||||
j
|
||||
just
|
||||
k
|
||||
keep
|
||||
keeps
|
||||
kept
|
||||
keys
|
||||
kg
|
||||
km
|
||||
know
|
||||
known
|
||||
knows
|
||||
l
|
||||
largely
|
||||
last
|
||||
lately
|
||||
later
|
||||
latter
|
||||
latterly
|
||||
least
|
||||
less
|
||||
lest
|
||||
let
|
||||
lets
|
||||
like
|
||||
liked
|
||||
likely
|
||||
line
|
||||
little
|
||||
'll
|
||||
'll
|
||||
look
|
||||
looking
|
||||
looks
|
||||
ltd
|
||||
m
|
||||
made
|
||||
mainly
|
||||
make
|
||||
makes
|
||||
many
|
||||
may
|
||||
maybe
|
||||
me
|
||||
mean
|
||||
means
|
||||
meantime
|
||||
meanwhile
|
||||
merely
|
||||
mg
|
||||
might
|
||||
million
|
||||
miss
|
||||
ml
|
||||
more
|
||||
moreover
|
||||
most
|
||||
mostly
|
||||
mr
|
||||
mrs
|
||||
much
|
||||
mug
|
||||
must
|
||||
my
|
||||
myself
|
||||
n
|
||||
na
|
||||
name
|
||||
namely
|
||||
nay
|
||||
nd
|
||||
near
|
||||
nearly
|
||||
necessarily
|
||||
necessary
|
||||
need
|
||||
needs
|
||||
neither
|
||||
never
|
||||
nevertheless
|
||||
new
|
||||
next
|
||||
nine
|
||||
ninety
|
||||
no
|
||||
nobody
|
||||
non
|
||||
none
|
||||
nonetheless
|
||||
noone
|
||||
nor
|
||||
normally
|
||||
nos
|
||||
not
|
||||
noted
|
||||
nothing
|
||||
now
|
||||
nowhere
|
||||
o
|
||||
obtain
|
||||
obtained
|
||||
obviously
|
||||
of
|
||||
off
|
||||
often
|
||||
oh
|
||||
ok
|
||||
okay
|
||||
old
|
||||
omitted
|
||||
on
|
||||
once
|
||||
one
|
||||
ones
|
||||
only
|
||||
onto
|
||||
or
|
||||
ord
|
||||
other
|
||||
others
|
||||
otherwise
|
||||
ought
|
||||
our
|
||||
ours
|
||||
ourselves
|
||||
out
|
||||
outside
|
||||
over
|
||||
overall
|
||||
owing
|
||||
own
|
||||
p
|
||||
page
|
||||
pages
|
||||
part
|
||||
particular
|
||||
particularly
|
||||
past
|
||||
per
|
||||
perhaps
|
||||
placed
|
||||
please
|
||||
plus
|
||||
poorly
|
||||
possible
|
||||
possibly
|
||||
potentially
|
||||
pp
|
||||
predominantly
|
||||
present
|
||||
previously
|
||||
primarily
|
||||
probably
|
||||
promptly
|
||||
proud
|
||||
provides
|
||||
put
|
||||
q
|
||||
que
|
||||
quickly
|
||||
quite
|
||||
qv
|
||||
r
|
||||
ran
|
||||
rather
|
||||
rd
|
||||
re
|
||||
readily
|
||||
really
|
||||
recent
|
||||
recently
|
||||
ref
|
||||
refs
|
||||
regarding
|
||||
regardless
|
||||
regards
|
||||
related
|
||||
relatively
|
||||
research
|
||||
respectively
|
||||
resulted
|
||||
resulting
|
||||
results
|
||||
right
|
||||
run
|
||||
s
|
||||
said
|
||||
same
|
||||
saw
|
||||
say
|
||||
saying
|
||||
says
|
||||
sec
|
||||
section
|
||||
see
|
||||
seeing
|
||||
seem
|
||||
seemed
|
||||
seeming
|
||||
seems
|
||||
seen
|
||||
self
|
||||
selves
|
||||
sent
|
||||
seven
|
||||
several
|
||||
shall
|
||||
she
|
||||
shed
|
||||
she'll
|
||||
shell
|
||||
shes
|
||||
should
|
||||
shouldn't
|
||||
shouldnt
|
||||
show
|
||||
showed
|
||||
shown
|
||||
showns
|
||||
shows
|
||||
significant
|
||||
significantly
|
||||
similar
|
||||
similarly
|
||||
since
|
||||
six
|
||||
slightly
|
||||
so
|
||||
some
|
||||
somebody
|
||||
somehow
|
||||
someone
|
||||
somethan
|
||||
something
|
||||
sometime
|
||||
sometimes
|
||||
somewhat
|
||||
somewhere
|
||||
soon
|
||||
sorry
|
||||
specifically
|
||||
specified
|
||||
specify
|
||||
specifying
|
||||
state
|
||||
states
|
||||
still
|
||||
stop
|
||||
strongly
|
||||
sub
|
||||
substantially
|
||||
successfully
|
||||
such
|
||||
sufficiently
|
||||
suggest
|
||||
sup
|
||||
sure
|
||||
t
|
||||
take
|
||||
taken
|
||||
taking
|
||||
tell
|
||||
tends
|
||||
th
|
||||
than
|
||||
thank
|
||||
thanks
|
||||
thanx
|
||||
that
|
||||
that'll
|
||||
thatll
|
||||
thats
|
||||
that've
|
||||
thatve
|
||||
the
|
||||
their
|
||||
theirs
|
||||
them
|
||||
themselves
|
||||
then
|
||||
thence
|
||||
there
|
||||
thereafter
|
||||
thereby
|
||||
thered
|
||||
therefore
|
||||
therein
|
||||
there'll
|
||||
therell
|
||||
thereof
|
||||
therere
|
||||
theres
|
||||
thereto
|
||||
thereupon
|
||||
there've
|
||||
thereve
|
||||
these
|
||||
they
|
||||
theyd
|
||||
they'll
|
||||
theyll
|
||||
theyre
|
||||
they've
|
||||
theyve
|
||||
think
|
||||
this
|
||||
those
|
||||
thou
|
||||
though
|
||||
thoughh
|
||||
thousand
|
||||
throug
|
||||
through
|
||||
throughout
|
||||
thru
|
||||
thus
|
||||
til
|
||||
tip
|
||||
to
|
||||
together
|
||||
too
|
||||
took
|
||||
toward
|
||||
towards
|
||||
tried
|
||||
tries
|
||||
truly
|
||||
try
|
||||
trying
|
||||
ts
|
||||
twice
|
||||
two
|
||||
u
|
||||
un
|
||||
under
|
||||
unfortunately
|
||||
unless
|
||||
unlike
|
||||
unlikely
|
||||
until
|
||||
unto
|
||||
up
|
||||
upon
|
||||
ups
|
||||
us
|
||||
use
|
||||
used
|
||||
useful
|
||||
usefully
|
||||
usefulness
|
||||
uses
|
||||
using
|
||||
usually
|
||||
v
|
||||
value
|
||||
various
|
||||
've
|
||||
've
|
||||
very
|
||||
via
|
||||
viz
|
||||
vol
|
||||
vols
|
||||
vs
|
||||
w
|
||||
want
|
||||
wants
|
||||
was
|
||||
wasn't
|
||||
wasnt
|
||||
way
|
||||
we
|
||||
wed
|
||||
welcome
|
||||
we'll
|
||||
well
|
||||
went
|
||||
were
|
||||
weren't
|
||||
werent
|
||||
we've
|
||||
weve
|
||||
what
|
||||
whatever
|
||||
what'll
|
||||
whatll
|
||||
whats
|
||||
when
|
||||
whence
|
||||
whenever
|
||||
where
|
||||
whereafter
|
||||
whereas
|
||||
whereby
|
||||
wherein
|
||||
wheres
|
||||
whereupon
|
||||
wherever
|
||||
whether
|
||||
which
|
||||
while
|
||||
whim
|
||||
whither
|
||||
who
|
||||
whod
|
||||
whoever
|
||||
whole
|
||||
who'll
|
||||
wholl
|
||||
whom
|
||||
whomever
|
||||
whos
|
||||
whose
|
||||
why
|
||||
widely
|
||||
will
|
||||
willing
|
||||
wish
|
||||
with
|
||||
within
|
||||
without
|
||||
won't
|
||||
wont
|
||||
words
|
||||
would
|
||||
wouldn't
|
||||
wouldnt
|
||||
www
|
||||
x
|
||||
y
|
||||
yes
|
||||
yet
|
||||
you
|
||||
youd
|
||||
you'll
|
||||
youll
|
||||
your
|
||||
youre
|
||||
yours
|
||||
yourself
|
||||
yourselves
|
||||
you've
|
||||
youve
|
||||
z
|
||||
zero
|
||||
@ -5,303 +5,20 @@
|
||||
* Use of this source code is governed by an MIT-style license that can be
|
||||
* found in the LICENSE file at https://angular.io/license
|
||||
*/
|
||||
const path = require('path');
|
||||
const fs = require('fs');
|
||||
const Package = require('dgeni').Package;
|
||||
|
||||
const jsdocPackage = require('dgeni-packages/jsdoc');
|
||||
const nunjucksPackage = require('dgeni-packages/nunjucks');
|
||||
const typescriptPackage = require('dgeni-packages/typescript');
|
||||
const gitPackage = require('dgeni-packages/git');
|
||||
const linksPackage = require('../links-package');
|
||||
const examplesPackage = require('../examples-package');
|
||||
const targetPackage = require('../target-package');
|
||||
const contentPackage = require('../content-package');
|
||||
const remarkPackage = require('../remark-package');
|
||||
const apiPackage = require('../angular-api-package');
|
||||
const contentPackage = require('../angular-content-package');
|
||||
|
||||
const PROJECT_ROOT = path.resolve(__dirname, '../../../..');
|
||||
const API_SOURCE_PATH = path.resolve(PROJECT_ROOT, 'packages');
|
||||
const AIO_PATH = path.resolve(PROJECT_ROOT, 'aio');
|
||||
const CONTENTS_PATH = path.resolve(AIO_PATH, 'content');
|
||||
const TEMPLATES_PATH = path.resolve(AIO_PATH, 'tools/transforms/templates');
|
||||
const OUTPUT_PATH = path.resolve(AIO_PATH, 'src/content');
|
||||
const DOCS_OUTPUT_PATH = path.resolve(OUTPUT_PATH, 'docs');
|
||||
module.exports = new Package('angular.io', [gitPackage, apiPackage, contentPackage])
|
||||
|
||||
module.exports =
|
||||
new Package(
|
||||
'angular.io', [
|
||||
jsdocPackage, nunjucksPackage, typescriptPackage, linksPackage, examplesPackage,
|
||||
gitPackage, targetPackage, contentPackage, remarkPackage
|
||||
])
|
||||
// This processor relies upon the versionInfo. See below...
|
||||
.processor(require('./processors/processNavigationMap'))
|
||||
|
||||
// Register the processors
|
||||
.processor(require('./processors/convertPrivateClassesToInterfaces'))
|
||||
.processor(require('./processors/generateApiListDoc'))
|
||||
.processor(require('./processors/generateKeywords'))
|
||||
.processor(require('./processors/createOverviewDump'))
|
||||
.processor(require('./processors/checkUnbalancedBackTicks'))
|
||||
.processor(require('./processors/addNotYetDocumentedProperty'))
|
||||
.processor(require('./processors/mergeDecoratorDocs'))
|
||||
.processor(require('./processors/extractDecoratedClasses'))
|
||||
.processor(require('./processors/matchUpDirectiveDecorators'))
|
||||
.processor(require('./processors/filterMemberDocs'))
|
||||
.processor(require('./processors/convertToJson'))
|
||||
.processor(require('./processors/markBarredODocsAsPrivate'))
|
||||
.processor(require('./processors/filterPrivateDocs'))
|
||||
.processor(require('./processors/filterIgnoredDocs'))
|
||||
.processor(require('./processors/fixInternalDocumentLinks'))
|
||||
.processor(require('./processors/processNavigationMap'))
|
||||
.processor(require('./processors/copyContentAssets'))
|
||||
// We don't include this in the angular-base package because the `versionInfo` stuff
|
||||
// accesses the file system and git, which is slow.
|
||||
.config(function(renderDocsProcessor, versionInfo) {
|
||||
// Add the version data to the renderer, for use in things like github links
|
||||
renderDocsProcessor.extraData.versionInfo = versionInfo;
|
||||
|
||||
// overrides base packageInfo and returns the one for the 'angular/angular' repo.
|
||||
.factory('packageInfo', function() { return require(path.resolve(PROJECT_ROOT, 'package.json')); })
|
||||
.factory(require('./readers/json'))
|
||||
.factory(require('./services/copyFolder'))
|
||||
|
||||
.config(function(checkAnchorLinksProcessor) {
|
||||
// TODO: re-enable
|
||||
checkAnchorLinksProcessor.$enabled = false;
|
||||
})
|
||||
|
||||
// Where do we get the source files?
|
||||
.config(function(
|
||||
readTypeScriptModules, readFilesProcessor, collectExamples, generateKeywordsProcessor, jsonFileReader) {
|
||||
|
||||
// API files are typescript
|
||||
readTypeScriptModules.basePath = API_SOURCE_PATH;
|
||||
readTypeScriptModules.ignoreExportsMatching = [/^_/];
|
||||
readTypeScriptModules.hidePrivateMembers = true;
|
||||
readFilesProcessor.fileReaders.push(jsonFileReader);
|
||||
readTypeScriptModules.sourceFiles = [
|
||||
'common/index.ts',
|
||||
'common/testing/index.ts',
|
||||
'core/index.ts',
|
||||
'core/testing/index.ts',
|
||||
'forms/index.ts',
|
||||
'http/index.ts',
|
||||
'http/testing/index.ts',
|
||||
'platform-browser/index.ts',
|
||||
'platform-browser/testing/index.ts',
|
||||
'platform-browser-dynamic/index.ts',
|
||||
'platform-browser-dynamic/testing/index.ts',
|
||||
'platform-server/index.ts',
|
||||
'platform-server/testing/index.ts',
|
||||
'platform-webworker/index.ts',
|
||||
'platform-webworker-dynamic/index.ts',
|
||||
'router/index.ts',
|
||||
'router/testing/index.ts',
|
||||
'upgrade/index.ts',
|
||||
'upgrade/static.ts',
|
||||
];
|
||||
|
||||
readFilesProcessor.basePath = PROJECT_ROOT;
|
||||
readFilesProcessor.sourceFiles = [
|
||||
{
|
||||
basePath: CONTENTS_PATH,
|
||||
include: CONTENTS_PATH + '/{cookbook,guide,tutorial}/**/*.md',
|
||||
fileReader: 'contentFileReader'
|
||||
},
|
||||
{
|
||||
basePath: CONTENTS_PATH + '/marketing',
|
||||
include: CONTENTS_PATH + '/marketing/**/*.{html,md}',
|
||||
fileReader: 'contentFileReader'
|
||||
},
|
||||
{
|
||||
basePath: CONTENTS_PATH,
|
||||
include: CONTENTS_PATH + '/*.md',
|
||||
exclude: [CONTENTS_PATH + '/index.md'],
|
||||
fileReader: 'contentFileReader'
|
||||
},
|
||||
{
|
||||
basePath: API_SOURCE_PATH,
|
||||
include: API_SOURCE_PATH + '/examples/**/*',
|
||||
fileReader: 'exampleFileReader'
|
||||
},
|
||||
{
|
||||
basePath: CONTENTS_PATH,
|
||||
include: CONTENTS_PATH + '/examples/**/*',
|
||||
exclude: [
|
||||
'**/*plnkr.no-link.html',
|
||||
'**/node_modules/**',
|
||||
// boilerplate files
|
||||
'**/*/src/systemjs-angular-loader.js',
|
||||
'**/*/src/systemjs.config.js',
|
||||
'**/*/src/tsconfig.json',
|
||||
'**/*/bs-config.e2e.json',
|
||||
'**/*/bs-config.json',
|
||||
'**/*/package.json',
|
||||
'**/*/tslint.json',
|
||||
// example files
|
||||
'**/_test-output',
|
||||
'**/protractor-helpers.js',
|
||||
'**/e2e-spec.js',
|
||||
'**/ts/**/*.js',
|
||||
'**/js-es6*/**/*.js',
|
||||
'**/ts-snippets/**/*.js',
|
||||
],
|
||||
fileReader: 'exampleFileReader'
|
||||
},
|
||||
{
|
||||
basePath: CONTENTS_PATH,
|
||||
include: CONTENTS_PATH + '/navigation.json',
|
||||
fileReader: 'jsonFileReader'
|
||||
},
|
||||
{
|
||||
basePath: CONTENTS_PATH,
|
||||
include: CONTENTS_PATH + '/marketing/contributors.json',
|
||||
fileReader: 'jsonFileReader'
|
||||
},
|
||||
{
|
||||
basePath: CONTENTS_PATH,
|
||||
include: CONTENTS_PATH + '/marketing/resources.json',
|
||||
fileReader: 'jsonFileReader'
|
||||
},
|
||||
];
|
||||
|
||||
collectExamples.exampleFolders = ['examples', 'examples'];
|
||||
|
||||
generateKeywordsProcessor.ignoreWordsFile = 'aio/tools/transforms/angular.io-package/ignore.words';
|
||||
generateKeywordsProcessor.docTypesToIgnore = ['example-region'];
|
||||
})
|
||||
|
||||
// Ignore certain problematic files
|
||||
.config(function(filterIgnoredDocs) {
|
||||
filterIgnoredDocs.ignore = [
|
||||
/\/VERSION$/ // Ignore the `VERSION` const, since it would be written to the same file as the `Version` class
|
||||
];
|
||||
})
|
||||
|
||||
// Where do we write the output files?
|
||||
.config(function(writeFilesProcessor) { writeFilesProcessor.outputFolder = DOCS_OUTPUT_PATH; })
|
||||
|
||||
|
||||
// Target environments
|
||||
.config(function(targetEnvironments) {
|
||||
const ALLOWED_LANGUAGES = ['ts', 'js', 'dart'];
|
||||
const TARGET_LANGUAGE = 'ts';
|
||||
|
||||
ALLOWED_LANGUAGES.forEach(target => targetEnvironments.addAllowed(target));
|
||||
targetEnvironments.activate(TARGET_LANGUAGE);
|
||||
|
||||
// TODO: we may need to do something with `linkDocsInlineTagDef`
|
||||
})
|
||||
|
||||
|
||||
// Configure jsdoc-style tag parsing
|
||||
.config(function(parseTagsProcessor, getInjectables, inlineTagProcessor) {
|
||||
// Load up all the tag definitions in the tag-defs folder
|
||||
parseTagsProcessor.tagDefinitions =
|
||||
parseTagsProcessor.tagDefinitions.concat(getInjectables(requireFolder('./tag-defs')));
|
||||
|
||||
// We actually don't want to parse param docs in this package as we are getting the data
|
||||
// out using TS
|
||||
// TODO: rewire the param docs to the params extracted from TS
|
||||
parseTagsProcessor.tagDefinitions.forEach(function(tagDef) {
|
||||
if (tagDef.name === 'param') {
|
||||
tagDef.docProperty = 'paramData';
|
||||
tagDef.transforms = [];
|
||||
}
|
||||
});
|
||||
|
||||
inlineTagProcessor.inlineTagDefinitions.push(require('./inline-tag-defs/anchor'));
|
||||
})
|
||||
|
||||
|
||||
|
||||
// Configure nunjucks rendering of docs via templates
|
||||
.config(function(
|
||||
renderDocsProcessor, versionInfo, templateFinder, templateEngine, getInjectables) {
|
||||
|
||||
// Where to find the templates for the doc rendering
|
||||
templateFinder.templateFolders = [TEMPLATES_PATH];
|
||||
|
||||
// Standard patterns for matching docs to templates
|
||||
templateFinder.templatePatterns = [
|
||||
'${ doc.template }', '${ doc.id }.${ doc.docType }.template.html',
|
||||
'${ doc.id }.template.html', '${ doc.docType }.template.html',
|
||||
'${ doc.id }.${ doc.docType }.template.js', '${ doc.id }.template.js',
|
||||
'${ doc.docType }.template.js', '${ doc.id }.${ doc.docType }.template.json',
|
||||
'${ doc.id }.template.json', '${ doc.docType }.template.json', 'common.template.html'
|
||||
];
|
||||
|
||||
// Nunjucks and Angular conflict in their template bindings so change Nunjucks
|
||||
templateEngine.config.tags = {variableStart: '{$', variableEnd: '$}'};
|
||||
|
||||
templateEngine.filters =
|
||||
templateEngine.filters.concat(getInjectables(requireFolder('./rendering')));
|
||||
|
||||
// Add the version data to the renderer, for use in things like github links
|
||||
renderDocsProcessor.extraData.versionInfo = versionInfo;
|
||||
|
||||
// helpers are made available to the nunjucks templates
|
||||
renderDocsProcessor.helpers.relativePath = function(from, to) {
|
||||
return path.relative(from, to);
|
||||
};
|
||||
})
|
||||
|
||||
|
||||
|
||||
// We are not going to be relaxed about ambiguous links
|
||||
.config(function(getLinkInfo) {
|
||||
getLinkInfo.useFirstAmbiguousLink = false;
|
||||
})
|
||||
|
||||
|
||||
|
||||
.config(function(
|
||||
computeIdsProcessor, computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc,
|
||||
generateKeywordsProcessor) {
|
||||
|
||||
const API_SEGMENT = 'api';
|
||||
const APP_SEGMENT = 'app';
|
||||
|
||||
generateApiListDoc.outputFolder = API_SEGMENT;
|
||||
generateKeywordsProcessor.outputFolder = APP_SEGMENT;
|
||||
|
||||
// Replace any path templates inherited from other packages
|
||||
// (we want full and transparent control)
|
||||
computePathsProcessor.pathTemplates = [
|
||||
{
|
||||
docTypes: ['module'],
|
||||
getPath: function computeModulePath(doc) {
|
||||
doc.moduleFolder = `${API_SEGMENT}/${doc.id.replace(/\/index$/, '')}`;
|
||||
return doc.moduleFolder;
|
||||
},
|
||||
outputPathTemplate: '${moduleFolder}.json'
|
||||
},
|
||||
{
|
||||
docTypes: EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'pipe']),
|
||||
pathTemplate: '${moduleDoc.moduleFolder}/${name}',
|
||||
outputPathTemplate: '${moduleDoc.moduleFolder}/${name}.json',
|
||||
},
|
||||
{docTypes: ['example-region'], getOutputPath: function() {}},
|
||||
{
|
||||
docTypes: ['content'],
|
||||
getPath: (doc) => `${doc.id.replace(/\/index$/, '')}`,
|
||||
outputPathTemplate: '${path}.json'
|
||||
},
|
||||
{docTypes: ['navigation-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'},
|
||||
{docTypes: ['contributors-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'},
|
||||
{docTypes: ['resources-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'}
|
||||
];
|
||||
})
|
||||
|
||||
.config(function(convertToJsonProcessor, EXPORT_DOC_TYPES) {
|
||||
convertToJsonProcessor.docTypes = EXPORT_DOC_TYPES.concat([
|
||||
'content', 'decorator', 'directive', 'pipe', 'module'
|
||||
]);
|
||||
})
|
||||
|
||||
.config(function(copyContentAssetsProcessor) {
|
||||
copyContentAssetsProcessor.assetMappings.push(
|
||||
{ from: path.resolve(CONTENTS_PATH, 'images'), to: path.resolve(OUTPUT_PATH, 'images') }
|
||||
);
|
||||
});
|
||||
|
||||
|
||||
function requireFolder(folderPath) {
|
||||
const absolutePath = path.resolve(__dirname, folderPath);
|
||||
return fs.readdirSync(absolutePath)
|
||||
.filter(p => !/[._]spec\.js$/.test(p)) // ignore spec files
|
||||
.map(p => require(path.resolve(absolutePath, p)));
|
||||
}
|
||||
});
|
||||
|
||||
@ -1,7 +0,0 @@
|
||||
module.exports = {
|
||||
name: 'a',
|
||||
description: 'A shorthand for creating heading anchors. Usage: `{@a some-id}`',
|
||||
handler: function(doc, tagName, tagDescription) {
|
||||
return '<a id="' + tagDescription.trim() + '"></a>';
|
||||
}
|
||||
};
|
||||
@ -1,9 +0,0 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright Google Inc. All Rights Reserved.
|
||||
*
|
||||
* Use of this source code is governed by an MIT-style license that can be
|
||||
* found in the LICENSE file at https://angular.io/license
|
||||
*/
|
||||
|
||||
export const x = 100;
|
||||
@ -1,42 +0,0 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright Google Inc. All Rights Reserved.
|
||||
*
|
||||
* Use of this source code is governed by an MIT-style license that can be
|
||||
* found in the LICENSE file at https://angular.io/license
|
||||
*/
|
||||
|
||||
/**
|
||||
* @module
|
||||
* @description
|
||||
* This is the module description
|
||||
*/
|
||||
|
||||
export * from './importedSrc';
|
||||
|
||||
/**
|
||||
* This is some random other comment
|
||||
*/
|
||||
|
||||
/**
|
||||
* This is MyClass
|
||||
*/
|
||||
export class MyClass {
|
||||
message: String;
|
||||
|
||||
/**
|
||||
* Create a new MyClass
|
||||
* @param {String} name The name to say hello to
|
||||
*/
|
||||
constructor(name) { this.message = 'hello ' + name; }
|
||||
|
||||
/**
|
||||
* Return a greeting message
|
||||
*/
|
||||
greet() { return this.message; }
|
||||
}
|
||||
|
||||
/**
|
||||
* An exported function
|
||||
*/
|
||||
export const myFn = (val: number) => val * 2;
|
||||
@ -1,37 +0,0 @@
|
||||
module.exports = function addNotYetDocumentedProperty(EXPORT_DOC_TYPES, log, createDocMessage) {
|
||||
return {
|
||||
$runAfter: ['tags-parsed'],
|
||||
$runBefore: ['rendering-docs'],
|
||||
$process: function(docs) {
|
||||
docs.forEach(function(doc) {
|
||||
|
||||
if (EXPORT_DOC_TYPES.indexOf(doc.docType) === -1) return;
|
||||
|
||||
// NotYetDocumented means that no top level comments and no member level comments
|
||||
doc.notYetDocumented = notYetDocumented(doc);
|
||||
|
||||
if (doc.constructorDoc) {
|
||||
doc.constructorDoc.notYetDocumented = notYetDocumented(doc.constructorDoc);
|
||||
doc.notYetDocumented = doc.notYetDocumented && doc.constructorDoc.notYetDocumented;
|
||||
}
|
||||
|
||||
if (doc.members) {
|
||||
doc.members.forEach(function(member) {
|
||||
member.notYetDocumented = notYetDocumented(member);
|
||||
doc.notYetDocumented = doc.notYetDocumented && member.notYetDocumented;
|
||||
});
|
||||
}
|
||||
|
||||
if (doc.notYetDocumented) {
|
||||
log.debug(createDocMessage('Not yet documented', doc));
|
||||
}
|
||||
});
|
||||
|
||||
return docs;
|
||||
}
|
||||
};
|
||||
};
|
||||
|
||||
function notYetDocumented(doc) {
|
||||
return !doc.noDescription && doc.description.trim().length == 0;
|
||||
}
|
||||
@ -1,147 +0,0 @@
|
||||
var testPackage = require('../../helpers/test-package');
|
||||
var Dgeni = require('dgeni');
|
||||
|
||||
describe('addNotYetDocumentedProperty', function() {
|
||||
var dgeni, injector, processor;
|
||||
|
||||
beforeEach(function() {
|
||||
dgeni = new Dgeni([testPackage('angular.io-package')]);
|
||||
injector = dgeni.configureInjector();
|
||||
processor = injector.get('addNotYetDocumentedProperty');
|
||||
});
|
||||
|
||||
it('should mark export docs with no description as "not yet documented"', function() {
|
||||
var a, b, c, d, a1, b1, c1, d1;
|
||||
var docs = [
|
||||
a = {id: 'a', docType: 'interface', description: 'some content'},
|
||||
b = {id: 'b', docType: 'class', description: 'some content'},
|
||||
c = {id: 'c', docType: 'var', description: 'some content'},
|
||||
d = {id: 'd', docType: 'function', description: 'some content'},
|
||||
a1 = {id: 'a1', docType: 'interface', description: ''},
|
||||
b1 = {id: 'b1', docType: 'class', description: ''},
|
||||
c1 = {id: 'c1', docType: 'var', description: ''},
|
||||
d1 = {id: 'd1', docType: 'function', description: ''}
|
||||
];
|
||||
|
||||
processor.$process(docs);
|
||||
|
||||
expect(a.notYetDocumented).toBeFalsy();
|
||||
expect(b.notYetDocumented).toBeFalsy();
|
||||
expect(c.notYetDocumented).toBeFalsy();
|
||||
expect(d.notYetDocumented).toBeFalsy();
|
||||
|
||||
expect(a1.notYetDocumented).toBeTruthy();
|
||||
expect(b1.notYetDocumented).toBeTruthy();
|
||||
expect(c1.notYetDocumented).toBeTruthy();
|
||||
expect(d1.notYetDocumented).toBeTruthy();
|
||||
});
|
||||
|
||||
it('should mark member docs with no description as "not yet documented"', function() {
|
||||
var a, a1, a2, b, b1, b2, c, c1, c2;
|
||||
var docs = [
|
||||
a = {
|
||||
id: 'a',
|
||||
docType: 'interface',
|
||||
description: 'some content',
|
||||
members: [a1 = {id: 'a1', description: 'some content'}, a2 = {id: 'a2', description: ''}]
|
||||
},
|
||||
b = {
|
||||
id: 'b',
|
||||
docType: 'class',
|
||||
description: '',
|
||||
members: [b1 = {id: 'b1', description: 'some content'}, b2 = {id: 'b2', description: ''}]
|
||||
},
|
||||
c = {
|
||||
id: 'c',
|
||||
docType: 'class',
|
||||
description: '',
|
||||
members: [c1 = {id: 'c1', description: ''}, c2 = {id: 'c2', description: ''}]
|
||||
},
|
||||
];
|
||||
|
||||
processor.$process(docs);
|
||||
|
||||
expect(a.notYetDocumented).toBeFalsy();
|
||||
expect(b.notYetDocumented).toBeFalsy();
|
||||
expect(c.notYetDocumented).toBeTruthy();
|
||||
|
||||
expect(a1.notYetDocumented).toBeFalsy();
|
||||
expect(a2.notYetDocumented).toBeTruthy();
|
||||
expect(b1.notYetDocumented).toBeFalsy();
|
||||
expect(b2.notYetDocumented).toBeTruthy();
|
||||
expect(c1.notYetDocumented).toBeTruthy();
|
||||
expect(c2.notYetDocumented).toBeTruthy();
|
||||
});
|
||||
|
||||
|
||||
it('should mark constructor doc with no description as "not yet documented"', function() {
|
||||
var a, a1, b, b1;
|
||||
var docs = [
|
||||
a = {
|
||||
id: 'a',
|
||||
docType: 'interface',
|
||||
description: '',
|
||||
constructorDoc: a1 = {id: 'a1', description: 'some content'}
|
||||
},
|
||||
b = {
|
||||
id: 'b',
|
||||
docType: 'interface',
|
||||
description: '',
|
||||
constructorDoc: b1 = {id: 'b1', description: ''}
|
||||
}
|
||||
];
|
||||
|
||||
processor.$process(docs);
|
||||
|
||||
expect(a.notYetDocumented).toBeFalsy();
|
||||
expect(b.notYetDocumented).toBeTruthy();
|
||||
|
||||
expect(a1.notYetDocumented).toBeFalsy();
|
||||
expect(b1.notYetDocumented).toBeTruthy();
|
||||
});
|
||||
|
||||
|
||||
it('should not mark documents explicity tagged as `@noDescription`', function() {
|
||||
var a, a1, a2, b, b1, b2, c, c1, c2;
|
||||
var docs = [
|
||||
a = {
|
||||
id: 'a',
|
||||
docType: 'interface',
|
||||
description: 'some content',
|
||||
members: [
|
||||
a1 = {id: 'a1', description: 'some content'},
|
||||
a2 = {id: 'a2', description: '', noDescription: true}
|
||||
]
|
||||
},
|
||||
b = {
|
||||
id: 'b',
|
||||
docType: 'class',
|
||||
description: '',
|
||||
members: [
|
||||
b1 = {id: 'b1', description: 'some content'},
|
||||
b2 = {id: 'b2', description: '', noDescription: true}
|
||||
]
|
||||
},
|
||||
c = {
|
||||
id: 'c',
|
||||
docType: 'class',
|
||||
description: '',
|
||||
noDescription: true,
|
||||
members: [c1 = {id: 'c1', description: ''}, c2 = {id: 'c2', description: ''}]
|
||||
},
|
||||
];
|
||||
|
||||
processor.$process(docs);
|
||||
|
||||
expect(a.notYetDocumented).toBeFalsy();
|
||||
expect(b.notYetDocumented).toBeFalsy();
|
||||
expect(c.notYetDocumented).toBeFalsy();
|
||||
|
||||
expect(a1.notYetDocumented).toBeFalsy();
|
||||
expect(a2.notYetDocumented).toBeFalsy();
|
||||
expect(b1.notYetDocumented).toBeFalsy();
|
||||
expect(b2.notYetDocumented).toBeFalsy();
|
||||
expect(c1.notYetDocumented).toBeTruthy();
|
||||
expect(c2.notYetDocumented).toBeTruthy();
|
||||
});
|
||||
});
|
||||
@ -1,33 +0,0 @@
|
||||
var _ = require('lodash');
|
||||
|
||||
/**
|
||||
* @dgProcessor checkUnbalancedBackTicks
|
||||
* @description
|
||||
* Searches the rendered content for an odd number of (```) backticks,
|
||||
* which would indicate an unbalanced pair and potentially a typo in the
|
||||
* source content.
|
||||
*/
|
||||
module.exports = function checkUnbalancedBackTicks(log, createDocMessage) {
|
||||
|
||||
var BACKTICK_REGEX = /^ *```/gm;
|
||||
|
||||
return {
|
||||
// $runAfter: ['checkAnchorLinksProcessor'],
|
||||
$runAfter: ['inlineTagProcessor'],
|
||||
$runBefore: ['writeFilesProcessor'],
|
||||
$process: function(docs) {
|
||||
_.forEach(docs, function(doc) {
|
||||
if (doc.renderedContent) {
|
||||
var matches = doc.renderedContent.match(BACKTICK_REGEX);
|
||||
if (matches && matches.length % 2 !== 0) {
|
||||
doc.unbalancedBackTicks = true;
|
||||
log.warn(createDocMessage(
|
||||
'checkUnbalancedBackTicks processor: unbalanced backticks found in rendered content',
|
||||
doc));
|
||||
log.warn(doc.renderedContent);
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
};
|
||||
};
|
||||
@ -1,29 +0,0 @@
|
||||
var testPackage = require('../../helpers/test-package');
|
||||
var Dgeni = require('dgeni');
|
||||
|
||||
describe('checkUnbalancedBackTicks', function() {
|
||||
var dgeni, injector, processor, log;
|
||||
|
||||
beforeEach(function() {
|
||||
dgeni = new Dgeni([testPackage('angular.io-package')]);
|
||||
injector = dgeni.configureInjector();
|
||||
processor = injector.get('checkUnbalancedBackTicks');
|
||||
log = injector.get('log');
|
||||
});
|
||||
|
||||
it('should warn if there are an odd number of back ticks in the rendered content', function() {
|
||||
var docs = [{
|
||||
renderedContent: '```\n' +
|
||||
'code block\n' +
|
||||
'```\n' +
|
||||
'```\n' +
|
||||
'code block with missing closing back ticks\n'
|
||||
}];
|
||||
|
||||
processor.$process(docs);
|
||||
|
||||
expect(log.warn).toHaveBeenCalledWith(
|
||||
'checkUnbalancedBackTicks processor: unbalanced backticks found in rendered content - doc');
|
||||
expect(docs[0].unbalancedBackTicks).toBe(true);
|
||||
});
|
||||
});
|
||||
@ -1,11 +0,0 @@
|
||||
module.exports = function convertPrivateClassesToInterfacesProcessor(
|
||||
convertPrivateClassesToInterfaces) {
|
||||
return {
|
||||
$runAfter: ['processing-docs'],
|
||||
$runBefore: ['docs-processed'],
|
||||
$process: function(docs) {
|
||||
convertPrivateClassesToInterfaces(docs, false);
|
||||
return docs;
|
||||
}
|
||||
};
|
||||
};
|
||||
@ -1,40 +0,0 @@
|
||||
module.exports = function convertToJsonProcessor(log, createDocMessage) {
|
||||
|
||||
return {
|
||||
$runAfter: ['checkUnbalancedBackTicks'],
|
||||
$runBefore: ['writeFilesProcessor'],
|
||||
docTypes: [],
|
||||
$process: function(docs) {
|
||||
const docTypes = this.docTypes;
|
||||
docs.forEach((doc) => {
|
||||
if (docTypes.indexOf(doc.docType) !== -1) {
|
||||
let contents = doc.renderedContent || '';
|
||||
|
||||
let title = doc.title;
|
||||
|
||||
// We do allow an empty `title` but resort to `name` if it is not even defined
|
||||
if (title === undefined) {
|
||||
title = doc.name;
|
||||
}
|
||||
|
||||
// If there is no title then try to extract it from the first h1 in the renderedContent
|
||||
if (title === undefined) {
|
||||
const match = /<h1[^>]*>(.+?)<\/h1>/.exec(contents);
|
||||
if (match) {
|
||||
title = match[1];
|
||||
}
|
||||
}
|
||||
|
||||
// If there is still no title then log a warning
|
||||
if (title === undefined) {
|
||||
title = '';
|
||||
log.warn(createDocMessage('Title property expected', doc));
|
||||
}
|
||||
|
||||
doc.renderedContent = JSON.stringify({ id: doc.path, title, contents }, null, 2);
|
||||
}
|
||||
});
|
||||
}
|
||||
};
|
||||
|
||||
};
|
||||
@ -1,71 +0,0 @@
|
||||
var testPackage = require('../../helpers/test-package');
|
||||
var Dgeni = require('dgeni');
|
||||
|
||||
describe('convertToJson processor', () => {
|
||||
var dgeni, injector, processor, log;
|
||||
|
||||
beforeAll(function() {
|
||||
dgeni = new Dgeni([testPackage('angular.io-package')]);
|
||||
injector = dgeni.configureInjector();
|
||||
processor = injector.get('convertToJsonProcessor');
|
||||
log = injector.get('log');
|
||||
processor.docTypes = ['test-doc'];
|
||||
});
|
||||
|
||||
it('should be part of the dgeni package', () => {
|
||||
expect(processor).toBeDefined();
|
||||
});
|
||||
|
||||
it('should convert the renderedContent to JSON', () => {
|
||||
const docs = [{
|
||||
docType: 'test-doc',
|
||||
title: 'The Title',
|
||||
name: 'The Name',
|
||||
path: 'test/doc',
|
||||
renderedContent: 'Some Content'
|
||||
}];
|
||||
processor.$process(docs);
|
||||
expect(JSON.parse(docs[0].renderedContent).id).toEqual('test/doc');
|
||||
expect(JSON.parse(docs[0].renderedContent).title).toEqual('The Title');
|
||||
expect(JSON.parse(docs[0].renderedContent).contents).toEqual('Some Content');
|
||||
});
|
||||
|
||||
it('should get the title from name if no title is specified', () => {
|
||||
const docs = [{ docType: 'test-doc', name: 'The Name' }];
|
||||
processor.$process(docs);
|
||||
expect(JSON.parse(docs[0].renderedContent).title).toEqual('The Name');
|
||||
});
|
||||
|
||||
it('should accept an empty title', () => {
|
||||
const docs = [{ docType: 'test-doc', title: '' }];
|
||||
processor.$process(docs);
|
||||
expect(JSON.parse(docs[0].renderedContent).title).toEqual('');
|
||||
expect(log.warn).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should accept an empty name if title is not provided', () => {
|
||||
const docs = [{ docType: 'test-doc', name: '' }];
|
||||
processor.$process(docs);
|
||||
expect(JSON.parse(docs[0].renderedContent).title).toEqual('');
|
||||
expect(log.warn).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should get the title from the first `h1` if no title nor name is specified', () => {
|
||||
const docs = [{ docType: 'test-doc', renderedContent: '<div><h1 class="title">Some title</h1><article><h1>Article 1</h1></article></div>' }];
|
||||
processor.$process(docs);
|
||||
expect(JSON.parse(docs[0].renderedContent).contents).toEqual('<div><h1 class="title">Some title</h1><article><h1>Article 1</h1></article></div>');
|
||||
expect(JSON.parse(docs[0].renderedContent).title).toEqual('Some title');
|
||||
});
|
||||
|
||||
it('should set missing titles to empty', () => {
|
||||
const docs = [{ docType: 'test-doc' }];
|
||||
processor.$process(docs);
|
||||
expect(JSON.parse(docs[0].renderedContent).title).toBe('');
|
||||
});
|
||||
|
||||
it('should log a warning', () => {
|
||||
const docs = [{ docType: 'test-doc' }];
|
||||
processor.$process(docs);
|
||||
expect(log.warn).toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
@ -1,12 +0,0 @@
|
||||
|
||||
module.exports = function copyContentAssetsProcessor(copyFolder) {
|
||||
return {
|
||||
$runAfter: ['files-written'],
|
||||
assetMappings: [],
|
||||
$process() {
|
||||
this.assetMappings.forEach(map => {
|
||||
copyFolder(map.from, map.to);
|
||||
});
|
||||
}
|
||||
};
|
||||
};
|
||||
@ -1,27 +0,0 @@
|
||||
const testPackage = require('../../helpers/test-package');
|
||||
const Dgeni = require('dgeni');
|
||||
const factory = require('./copyContentAssets');
|
||||
|
||||
describe('extractDecoratedClasses processor', function() {
|
||||
let dgeni, injector, processor;
|
||||
|
||||
beforeEach(function() {
|
||||
dgeni = new Dgeni([testPackage('angular.io-package')]);
|
||||
injector = dgeni.configureInjector();
|
||||
processor = injector.get('copyContentAssetsProcessor');
|
||||
});
|
||||
|
||||
it('should exist', () => {
|
||||
expect(processor).toBeDefined();
|
||||
});
|
||||
|
||||
it('should call copyFolder with each mapping', () => {
|
||||
const mockCopyFolder = jasmine.createSpy();
|
||||
processor = factory(mockCopyFolder);
|
||||
processor.assetMappings.push({ from: 'a/b/c', to: 'x/y/z' });
|
||||
processor.assetMappings.push({ from: '1/2/3', to: '4/5/6' });
|
||||
processor.$process();
|
||||
expect(mockCopyFolder).toHaveBeenCalledWith('a/b/c', 'x/y/z');
|
||||
expect(mockCopyFolder).toHaveBeenCalledWith('1/2/3', '4/5/6');
|
||||
});
|
||||
});
|
||||
@ -1,24 +0,0 @@
|
||||
var _ = require('lodash');
|
||||
|
||||
module.exports = function createOverviewDump() {
|
||||
|
||||
return {
|
||||
$runAfter: ['processing-docs'],
|
||||
$runBefore: ['docs-processed'],
|
||||
$process: function(docs) {
|
||||
var overviewDoc = {
|
||||
id: 'overview-dump',
|
||||
aliases: ['overview-dump'],
|
||||
path: 'overview-dump',
|
||||
outputPath: 'overview-dump.html',
|
||||
modules: []
|
||||
};
|
||||
_.forEach(docs, function(doc) {
|
||||
if (doc.docType === 'module') {
|
||||
overviewDoc.modules.push(doc);
|
||||
}
|
||||
});
|
||||
docs.push(overviewDoc);
|
||||
}
|
||||
};
|
||||
};
|
||||
@ -1,29 +0,0 @@
|
||||
var _ = require('lodash');
|
||||
|
||||
module.exports = function extractDecoratedClassesProcessor(EXPORT_DOC_TYPES) {
|
||||
|
||||
// Add the "directive" docType into those that can be exported from a module
|
||||
EXPORT_DOC_TYPES.push('directive', 'pipe');
|
||||
|
||||
return {
|
||||
$runAfter: ['processing-docs'],
|
||||
$runBefore: ['docs-processed'],
|
||||
decoratorTypes: ['Directive', 'Component', 'Pipe'],
|
||||
$process: function(docs) {
|
||||
var decoratorTypes = this.decoratorTypes;
|
||||
|
||||
_.forEach(docs, function(doc) {
|
||||
|
||||
_.forEach(doc.decorators, function(decorator) {
|
||||
|
||||
if (decoratorTypes.indexOf(decorator.name) !== -1) {
|
||||
doc.docType = decorator.name.toLowerCase();
|
||||
doc[doc.docType + 'Options'] = decorator.argumentInfo[0];
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
return docs;
|
||||
}
|
||||
};
|
||||
};
|
||||
@ -1,48 +0,0 @@
|
||||
var testPackage = require('../../helpers/test-package');
|
||||
var Dgeni = require('dgeni');
|
||||
|
||||
describe('extractDecoratedClasses processor', function() {
|
||||
var dgeni, injector, processor;
|
||||
|
||||
beforeEach(function() {
|
||||
dgeni = new Dgeni([testPackage('angular.io-package')]);
|
||||
injector = dgeni.configureInjector();
|
||||
processor = injector.get('extractDecoratedClassesProcessor');
|
||||
});
|
||||
|
||||
it('should extract specified decorator arguments', function() {
|
||||
var doc1 = {
|
||||
id: '@angular/common/ngFor',
|
||||
name: 'ngFor',
|
||||
docType: 'class',
|
||||
decorators: [{
|
||||
name: 'Directive',
|
||||
arguments: ['{selector: \'[ng-for][ng-for-of]\', properties: [\'ngForOf\']}'],
|
||||
argumentInfo: [{selector: '[ng-for][ng-for-of]', properties: ['ngForOf']}]
|
||||
}]
|
||||
};
|
||||
var doc2 = {
|
||||
id: '@angular/core/DecimalPipe',
|
||||
name: 'DecimalPipe',
|
||||
docType: 'class',
|
||||
decorators:
|
||||
[{name: 'Pipe', arguments: ['{name: \'number\'}'], argumentInfo: [{name: 'number'}]}]
|
||||
};
|
||||
|
||||
processor.$process([doc1, doc2]);
|
||||
|
||||
expect(doc1).toEqual(jasmine.objectContaining({
|
||||
id: '@angular/common/ngFor',
|
||||
name: 'ngFor',
|
||||
docType: 'directive',
|
||||
directiveOptions: {selector: '[ng-for][ng-for-of]', properties: ['ngForOf']}
|
||||
}));
|
||||
|
||||
expect(doc2).toEqual(jasmine.objectContaining({
|
||||
id: '@angular/core/DecimalPipe',
|
||||
name: 'DecimalPipe',
|
||||
docType: 'pipe',
|
||||
pipeOptions: {name: 'number'}
|
||||
}));
|
||||
});
|
||||
});
|
||||
@ -1,13 +0,0 @@
|
||||
/**
|
||||
* Filter out docs whose id matches a pattern in the `filterIgnoredDocs.ignore` list
|
||||
*/
|
||||
module.exports = function filterIgnoredDocs() {
|
||||
return {
|
||||
ignore: [],
|
||||
$runAfter: ['ids-computed'],
|
||||
$runBefore: ['computing-paths'],
|
||||
$process: function(docs) {
|
||||
return docs.filter(doc => !this.ignore.some(regexp => regexp.test(doc.id)));
|
||||
}
|
||||
};
|
||||
};
|
||||
@ -1,39 +0,0 @@
|
||||
const testPackage = require('../../helpers/test-package');
|
||||
const processorFactory = require('./filterIgnoredDocs');
|
||||
const Dgeni = require('dgeni');
|
||||
|
||||
describe('filterIgnoredDocs processor', () => {
|
||||
|
||||
it('should be available on the injector', () => {
|
||||
const dgeni = new Dgeni([testPackage('angular.io-package')]);
|
||||
const injector = dgeni.configureInjector();
|
||||
const processor = injector.get('filterIgnoredDocs');
|
||||
expect(processor.$process).toBeDefined();
|
||||
});
|
||||
|
||||
it('should run before the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runBefore).toEqual(['computing-paths']);
|
||||
});
|
||||
|
||||
it('should run after the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runAfter).toEqual(['ids-computed']);
|
||||
});
|
||||
|
||||
it('should remove docs that match the ignore list', () => {
|
||||
const processor = processorFactory();
|
||||
processor.ignore = [/\/VERSION$/, /ignore-me/];
|
||||
const docs = [
|
||||
{ id: 'public1'},
|
||||
{ id: 'ignore-me/something' },
|
||||
{ id: 'public2'},
|
||||
{ id: 'and-me/VERSION' }
|
||||
];
|
||||
const filteredDocs = processor.$process(docs);
|
||||
expect(filteredDocs).toEqual([
|
||||
{ id: 'public1'},
|
||||
{ id: 'public2'}
|
||||
]);
|
||||
});
|
||||
});
|
||||
@ -1,7 +0,0 @@
|
||||
module.exports = function filterMemberDocs() {
|
||||
return {
|
||||
$runAfter: ['extra-docs-added'], $runBefore: ['computing-paths'], $process: function(docs) {
|
||||
return docs.filter(function(doc) { return doc.docType !== 'member'; });
|
||||
}
|
||||
};
|
||||
};
|
||||
@ -1,9 +0,0 @@
|
||||
module.exports = function filterPrivateDocs() {
|
||||
return {
|
||||
$runAfter: ['extra-docs-added'],
|
||||
$runBefore: ['computing-paths'],
|
||||
$process: function(docs) {
|
||||
return docs.filter(function(doc) { return doc.privateExport !== true; });
|
||||
}
|
||||
};
|
||||
};
|
||||
@ -1,40 +0,0 @@
|
||||
const testPackage = require('../../helpers/test-package');
|
||||
const processorFactory = require('./filterPrivateDocs');
|
||||
const Dgeni = require('dgeni');
|
||||
|
||||
describe('filterPrivateDocs processor', () => {
|
||||
|
||||
it('should be available on the injector', () => {
|
||||
const dgeni = new Dgeni([testPackage('angular.io-package')]);
|
||||
const injector = dgeni.configureInjector();
|
||||
const processor = injector.get('filterPrivateDocs');
|
||||
expect(processor.$process).toBeDefined();
|
||||
});
|
||||
|
||||
it('should run before the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runBefore).toEqual(['computing-paths']);
|
||||
});
|
||||
|
||||
it('should run after the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runAfter).toEqual(['extra-docs-added']);
|
||||
});
|
||||
|
||||
it('should remove docs that are marked as private exports', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{ name: 'public1'},
|
||||
{ name: 'ɵPrivate1', privateExport: true },
|
||||
{ name: 'public2'},
|
||||
{ name: 'ɵPrivate2', privateExport: true },
|
||||
{ id: 'other'}
|
||||
];
|
||||
const filteredDocs = processor.$process(docs);
|
||||
expect(filteredDocs).toEqual([
|
||||
{ name: 'public1'},
|
||||
{ name: 'public2'},
|
||||
{ id: 'other'}
|
||||
]);
|
||||
});
|
||||
});
|
||||
@ -1,24 +0,0 @@
|
||||
/**
|
||||
* @dgProcessor fixInternalDocumentLinks
|
||||
* @description
|
||||
* Add in the document path to links that start with a hash.
|
||||
* This is important when the web app has a base href in place,
|
||||
* since links like: `<a href="#some-id">` would get mapped to
|
||||
* the URL `base/#some-id` even if the current location is `base/some/doc`.
|
||||
*/
|
||||
module.exports = function fixInternalDocumentLinks() {
|
||||
|
||||
var INTERNAL_LINK = /(<a [^>]*href=")(#[^"]*)/g;
|
||||
|
||||
return {
|
||||
$runAfter: ['inlineTagProcessor'],
|
||||
$runBefore: ['convertToJsonProcessor'],
|
||||
$process: function(docs) {
|
||||
docs.forEach(doc => {
|
||||
doc.renderedContent = doc.renderedContent.replace(INTERNAL_LINK, (_, pre, hash) => {
|
||||
return pre + doc.path + hash;
|
||||
});
|
||||
});
|
||||
}
|
||||
};
|
||||
};
|
||||
@ -1,52 +0,0 @@
|
||||
const testPackage = require('../../helpers/test-package');
|
||||
const processorFactory = require('./fixInternalDocumentLinks');
|
||||
const Dgeni = require('dgeni');
|
||||
|
||||
describe('fixInternalDocumentLinks processor', () => {
|
||||
|
||||
it('should be available on the injector', () => {
|
||||
const dgeni = new Dgeni([testPackage('angular.io-package')]);
|
||||
const injector = dgeni.configureInjector();
|
||||
const processor = injector.get('fixInternalDocumentLinks');
|
||||
expect(processor.$process).toBeDefined();
|
||||
});
|
||||
|
||||
it('should run before the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runBefore).toEqual(['convertToJsonProcessor']);
|
||||
});
|
||||
|
||||
it('should run after the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runAfter).toEqual(['inlineTagProcessor']);
|
||||
});
|
||||
|
||||
it('should prefix internal hash links with the current doc path', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{
|
||||
path: 'some/doc',
|
||||
renderedContent: `
|
||||
<a href="http://google.com#q=angular">Google</a>
|
||||
<a href="some/relative/path#some-id">Some Id</a>
|
||||
<a href="#some-internal-id">Link to heading</a>
|
||||
<a class="important" href="#some-internal-id">Link to heading</a>
|
||||
<a href="#some-internal-id" target="_blank">Link to heading</a>
|
||||
`
|
||||
},
|
||||
];
|
||||
processor.$process(docs);
|
||||
expect(docs).toEqual([
|
||||
{
|
||||
path: 'some/doc',
|
||||
renderedContent: `
|
||||
<a href="http://google.com#q=angular">Google</a>
|
||||
<a href="some/relative/path#some-id">Some Id</a>
|
||||
<a href="some/doc#some-internal-id">Link to heading</a>
|
||||
<a class="important" href="some/doc#some-internal-id">Link to heading</a>
|
||||
<a href="some/doc#some-internal-id" target="_blank">Link to heading</a>
|
||||
`
|
||||
},
|
||||
]);
|
||||
});
|
||||
});
|
||||
@ -1,55 +0,0 @@
|
||||
module.exports = function generateApiListDoc() {
|
||||
|
||||
return {
|
||||
$runAfter: ['extra-docs-added'],
|
||||
$runBefore: ['rendering-docs'],
|
||||
outputFolder: null,
|
||||
$validate: {outputFolder: {presence: true}},
|
||||
$process: function(docs) {
|
||||
docs.push({
|
||||
docType: 'api-list-data',
|
||||
template: 'json-doc.template.json',
|
||||
path: this.outputFolder + '/api-list.json',
|
||||
outputPath: this.outputFolder + '/api-list.json',
|
||||
data: docs
|
||||
.filter(doc => doc.docType === 'module')
|
||||
.map(getModuleInfo)
|
||||
});
|
||||
}
|
||||
};
|
||||
};
|
||||
|
||||
function getModuleInfo(moduleDoc) {
|
||||
const moduleName = moduleDoc.id.replace(/\/index$/, '');
|
||||
return {
|
||||
name: moduleName.toLowerCase(),
|
||||
title: moduleName,
|
||||
items: moduleDoc.exports
|
||||
// Ignore internals and private exports (indicated by the ɵ prefix)
|
||||
.filter(doc => !doc.internal && !doc.privateExport).map(getExportInfo)
|
||||
};
|
||||
}
|
||||
|
||||
function getExportInfo(exportDoc) {
|
||||
return {
|
||||
name: exportDoc.name.toLowerCase(),
|
||||
title: exportDoc.name,
|
||||
path: exportDoc.path,
|
||||
docType: getDocType(exportDoc),
|
||||
stability: getStability(exportDoc),
|
||||
securityRisk: !!exportDoc.security
|
||||
};
|
||||
}
|
||||
|
||||
function getDocType(doc) {
|
||||
// We map `let` and `var` types to `const`
|
||||
if (['let', 'var'].indexOf(doc.docType) !== -1) {
|
||||
return 'const';
|
||||
}
|
||||
return doc.docType;
|
||||
}
|
||||
|
||||
const stabilityProperties = ['stable', 'experimental', 'deprecated'];
|
||||
function getStability(doc) {
|
||||
return stabilityProperties.find(prop => doc.hasOwnProperty(prop)) || '';
|
||||
}
|
||||
@ -1,152 +0,0 @@
|
||||
const testPackage = require('../../helpers/test-package');
|
||||
const processorFactory = require('./generateApiListDoc');
|
||||
const Dgeni = require('dgeni');
|
||||
|
||||
describe('generateApiListDoc processor', () => {
|
||||
|
||||
it('should be available on the injector', () => {
|
||||
const dgeni = new Dgeni([testPackage('angular.io-package')]);
|
||||
const injector = dgeni.configureInjector();
|
||||
const processor = injector.get('generateApiListDoc');
|
||||
expect(processor.$process).toBeDefined();
|
||||
});
|
||||
|
||||
it('should run after the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runAfter).toEqual(['extra-docs-added']);
|
||||
});
|
||||
|
||||
it('should run before the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runBefore).toEqual(['rendering-docs']);
|
||||
});
|
||||
|
||||
it('should create a new api list doc', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [];
|
||||
processor.outputFolder = 'test/path';
|
||||
processor.$process(docs);
|
||||
expect(docs[0]).toEqual({
|
||||
docType: 'api-list-data',
|
||||
template: 'json-doc.template.json',
|
||||
path: 'test/path/api-list.json',
|
||||
outputPath: 'test/path/api-list.json',
|
||||
data: []
|
||||
});
|
||||
});
|
||||
|
||||
it('should add an info object to the doc for each module doc', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{ docType: 'module', id: '@angular/common/index', exports: [] },
|
||||
{ docType: 'module', id: '@angular/core/index', exports: [] },
|
||||
{ docType: 'module', id: '@angular/http/index', exports: [] },
|
||||
];
|
||||
processor.$process(docs);
|
||||
expect(docs[3].data).toEqual([
|
||||
{ name: '@angular/common', title: '@angular/common', items: [] },
|
||||
{ name: '@angular/core', title: '@angular/core', items: [] },
|
||||
{ name: '@angular/http', title: '@angular/http', items: [] },
|
||||
]);
|
||||
});
|
||||
|
||||
it('should add info about each export on each module', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{ docType: 'module', id: '@angular/common/index', exports: [
|
||||
{ docType: 'directive', name: 'AaaAaa', path: 'aaa' },
|
||||
{ docType: 'pipe', name: 'BbbBbb', path: 'bbb' },
|
||||
{ docType: 'decorator', name: 'CccCcc', path: 'ccc' },
|
||||
{ docType: 'class', name: 'DddDdd', path: 'ddd' }
|
||||
] },
|
||||
{ docType: 'module', id: '@angular/core/index', exports: [
|
||||
{ docType: 'interface', name: 'EeeEee', path: 'eee' },
|
||||
{ docType: 'function', name: 'FffFff', path: 'fff' },
|
||||
{ docType: 'enum', name: 'GggGgg', path: 'ggg' },
|
||||
{ docType: 'type-alias', name: 'HhhHhh', path: 'hhh' },
|
||||
{ docType: 'const', name: 'IiiIii', path: 'iii' },
|
||||
] },
|
||||
];
|
||||
processor.$process(docs);
|
||||
expect(docs[2].data[0].items).toEqual([
|
||||
{ docType: 'directive', title: 'AaaAaa', name: 'aaaaaa', path: 'aaa', stability: '', securityRisk: false },
|
||||
{ docType: 'pipe', title: 'BbbBbb', name: 'bbbbbb', path: 'bbb', stability: '', securityRisk: false },
|
||||
{ docType: 'decorator', title: 'CccCcc', name: 'cccccc', path: 'ccc', stability: '', securityRisk: false },
|
||||
{ docType: 'class', title: 'DddDdd', name: 'dddddd', path: 'ddd', stability: '', securityRisk: false }
|
||||
]);
|
||||
expect(docs[2].data[1].items).toEqual([
|
||||
{ docType: 'interface', title: 'EeeEee', name: 'eeeeee', path: 'eee', stability: '', securityRisk: false },
|
||||
{ docType: 'function', title: 'FffFff', name: 'ffffff', path: 'fff', stability: '', securityRisk: false },
|
||||
{ docType: 'enum', title: 'GggGgg', name: 'gggggg', path: 'ggg', stability: '', securityRisk: false },
|
||||
{ docType: 'type-alias', title: 'HhhHhh', name: 'hhhhhh', path: 'hhh', stability: '', securityRisk: false },
|
||||
{ docType: 'const', title: 'IiiIii', name: 'iiiiii', path: 'iii', stability: '', securityRisk: false },
|
||||
]);
|
||||
});
|
||||
|
||||
it('should ignore internal and private exports', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{ docType: 'module', id: '@angular/common/index', exports: [
|
||||
{ docType: 'directive', name: 'AaaAaa', path: 'aaa', internal: true },
|
||||
{ docType: 'class', name: 'XxxXxx', path: 'xxx', privateExport: true },
|
||||
{ docType: 'pipe', name: 'BbbBbb', path: 'bbb' }
|
||||
]}
|
||||
];
|
||||
processor.$process(docs);
|
||||
expect(docs[1].data[0].items).toEqual([
|
||||
{ docType: 'pipe', title: 'BbbBbb', name: 'bbbbbb', path: 'bbb', stability: '', securityRisk: false },
|
||||
]);
|
||||
});
|
||||
|
||||
it('should convert `let` and `var` docTypes to `const`', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{ docType: 'module', id: '@angular/common/index', exports: [
|
||||
{ docType: 'var', name: 'AaaAaa', path: 'aaa' },
|
||||
{ docType: 'let', name: 'BbbBbb', path: 'bbb' },
|
||||
]}
|
||||
];
|
||||
processor.$process(docs);
|
||||
expect(docs[1].data[0].items).toEqual([
|
||||
{ docType: 'const', title: 'AaaAaa', name: 'aaaaaa', path: 'aaa', stability: '', securityRisk: false },
|
||||
{ docType: 'const', title: 'BbbBbb', name: 'bbbbbb', path: 'bbb', stability: '', securityRisk: false },
|
||||
]);
|
||||
});
|
||||
|
||||
|
||||
it('should convert security to a boolean securityRisk', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{ docType: 'module', id: '@angular/common/index', exports: [
|
||||
{ docType: 'class', name: 'AaaAaa', path: 'aaa', security: 'This is a security risk' },
|
||||
{ docType: 'class', name: 'BbbBbb', path: 'bbb', security: '' },
|
||||
]}
|
||||
];
|
||||
processor.$process(docs);
|
||||
expect(docs[1].data[0].items).toEqual([
|
||||
{ docType: 'class', title: 'AaaAaa', name: 'aaaaaa', path: 'aaa', stability: '', securityRisk: true },
|
||||
{ docType: 'class', title: 'BbbBbb', name: 'bbbbbb', path: 'bbb', stability: '', securityRisk: false },
|
||||
]);
|
||||
});
|
||||
|
||||
|
||||
it('should convert stability tags to the stable string property', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{ docType: 'module', id: '@angular/common/index', exports: [
|
||||
{ docType: 'class', name: 'AaaAaa', path: 'aaa', stable: undefined },
|
||||
{ docType: 'class', name: 'BbbBbb', path: 'bbb', experimental: 'Some message' },
|
||||
{ docType: 'class', name: 'CccCcc', path: 'ccc', deprecated: null },
|
||||
{ docType: 'class', name: 'DddDdd', path: 'ddd' },
|
||||
]}
|
||||
];
|
||||
processor.$process(docs);
|
||||
expect(docs[1].data[0].items).toEqual([
|
||||
{ docType: 'class', title: 'AaaAaa', name: 'aaaaaa', path: 'aaa', stability: 'stable', securityRisk: false },
|
||||
{ docType: 'class', title: 'BbbBbb', name: 'bbbbbb', path: 'bbb', stability: 'experimental', securityRisk: false },
|
||||
{ docType: 'class', title: 'CccCcc', name: 'cccccc', path: 'ccc', stability: 'deprecated', securityRisk: false },
|
||||
{ docType: 'class', title: 'DddDdd', name: 'dddddd', path: 'ddd', stability: '', securityRisk: false },
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
@ -1,142 +0,0 @@
|
||||
'use strict';
|
||||
|
||||
var fs = require('fs');
|
||||
var path = require('canonical-path');
|
||||
|
||||
/**
|
||||
* @dgProcessor generateKeywordsProcessor
|
||||
* @description
|
||||
* This processor extracts all the keywords from each document and creates
|
||||
* a new document that will be rendered as a JavaScript file containing all
|
||||
* this data.
|
||||
*/
|
||||
module.exports = function generateKeywordsProcessor(log, readFilesProcessor) {
|
||||
return {
|
||||
ignoreWordsFile: undefined,
|
||||
propertiesToIgnore: [],
|
||||
docTypesToIgnore: [],
|
||||
outputFolder: '',
|
||||
$validate: {
|
||||
ignoreWordsFile: {},
|
||||
docTypesToIgnore: {},
|
||||
propertiesToIgnore: {},
|
||||
outputFolder: {presence: true}
|
||||
},
|
||||
$runAfter: ['paths-computed'],
|
||||
$runBefore: ['rendering-docs'],
|
||||
$process: function(docs) {
|
||||
|
||||
// Keywords to ignore
|
||||
var wordsToIgnore = [];
|
||||
var propertiesToIgnore;
|
||||
var docTypesToIgnore;
|
||||
|
||||
// Keywords start with "ng:" or one of $, _ or a letter
|
||||
var KEYWORD_REGEX = /^((ng:|[$_a-z])[\w\-_]+)/;
|
||||
|
||||
// Load up the keywords to ignore, if specified in the config
|
||||
if (this.ignoreWordsFile) {
|
||||
var ignoreWordsPath = path.resolve(readFilesProcessor.basePath, this.ignoreWordsFile);
|
||||
wordsToIgnore = fs.readFileSync(ignoreWordsPath, 'utf8').toString().split(/[,\s\n\r]+/gm);
|
||||
|
||||
log.debug('Loaded ignore words from "' + ignoreWordsPath + '"');
|
||||
log.silly(wordsToIgnore);
|
||||
}
|
||||
|
||||
propertiesToIgnore = convertToMap(this.propertiesToIgnore);
|
||||
log.debug('Properties to ignore', propertiesToIgnore);
|
||||
docTypesToIgnore = convertToMap(this.docTypesToIgnore);
|
||||
log.debug('Doc types to ignore', docTypesToIgnore);
|
||||
|
||||
var ignoreWordsMap = convertToMap(wordsToIgnore);
|
||||
|
||||
// If the title contains a name starting with ng, e.g. "ngController", then add the module
|
||||
// name
|
||||
// without the ng to the title text, e.g. "controller".
|
||||
function extractTitleWords(title) {
|
||||
var match = /ng([A-Z]\w*)/.exec(title);
|
||||
if (match) {
|
||||
title = title + ' ' + match[1].toLowerCase();
|
||||
}
|
||||
return title;
|
||||
}
|
||||
|
||||
function extractWords(text, words, keywordMap) {
|
||||
var tokens = text.toLowerCase().split(/[.\s,`'"#]+/mg);
|
||||
tokens.forEach(function(token) {
|
||||
var match = token.match(KEYWORD_REGEX);
|
||||
if (match) {
|
||||
var key = match[1];
|
||||
if (!keywordMap[key]) {
|
||||
keywordMap[key] = true;
|
||||
words.push(key);
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
const filteredDocs = docs
|
||||
// We are not interested in some docTypes
|
||||
.filter(function(doc) { return !docTypesToIgnore[doc.docType]; })
|
||||
// Ignore internals and private exports (indicated by the ɵ prefix)
|
||||
.filter(function(doc) { return !doc.internal && !doc.privateExport; });
|
||||
|
||||
filteredDocs.forEach(function(doc) {
|
||||
|
||||
|
||||
var words = [];
|
||||
var keywordMap = Object.assign({}, ignoreWordsMap);
|
||||
var members = [];
|
||||
var membersMap = {};
|
||||
|
||||
// Search each top level property of the document for search terms
|
||||
Object.keys(doc).forEach(function(key) {
|
||||
const value = doc[key];
|
||||
|
||||
if (isString(value) && !propertiesToIgnore[key]) {
|
||||
extractWords(value, words, keywordMap);
|
||||
}
|
||||
|
||||
if (key === 'methods' || key === 'properties' || key === 'events') {
|
||||
value.forEach(function(member) { extractWords(member.name, members, membersMap); });
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
doc.searchTerms = {
|
||||
titleWords: extractTitleWords(doc.title || doc.name),
|
||||
keywords: words.sort().join(' '),
|
||||
members: members.sort().join(' ')
|
||||
};
|
||||
|
||||
});
|
||||
|
||||
var searchData =
|
||||
filteredDocs.filter(function(page) { return page.searchTerms; }).map(function(page) {
|
||||
return Object.assign(
|
||||
{path: page.path, title: page.name || page.title, type: page.docType}, page.searchTerms);
|
||||
});
|
||||
|
||||
docs.push({
|
||||
docType: 'json-doc',
|
||||
id: 'search-data-json',
|
||||
template: 'json-doc.template.json',
|
||||
path: this.outputFolder + '/search-data.json',
|
||||
outputPath: this.outputFolder + '/search-data.json',
|
||||
data: searchData
|
||||
});
|
||||
}
|
||||
};
|
||||
};
|
||||
|
||||
|
||||
function isString(value) {
|
||||
return typeof value == 'string';
|
||||
}
|
||||
|
||||
function convertToMap(collection) {
|
||||
const obj = {};
|
||||
collection.forEach(key => { obj[key] = true; });
|
||||
return obj;
|
||||
}
|
||||
@ -1,41 +0,0 @@
|
||||
const testPackage = require('../../helpers/test-package');
|
||||
const mockLogger = require('dgeni/lib/mocks/log')(false);
|
||||
const processorFactory = require('./generateKeywords');
|
||||
const Dgeni = require('dgeni');
|
||||
|
||||
const mockReadFilesProcessor = {
|
||||
basePath: 'base/path'
|
||||
};
|
||||
|
||||
describe('generateKeywords processor', () => {
|
||||
|
||||
it('should be available on the injector', () => {
|
||||
const dgeni = new Dgeni([testPackage('angular.io-package')]);
|
||||
const injector = dgeni.configureInjector();
|
||||
const processor = injector.get('generateKeywordsProcessor');
|
||||
expect(processor.$process).toBeDefined();
|
||||
});
|
||||
|
||||
it('should run after the correct processor', () => {
|
||||
const processor = processorFactory(mockLogger, mockReadFilesProcessor);
|
||||
expect(processor.$runAfter).toEqual(['paths-computed']);
|
||||
});
|
||||
|
||||
it('should run before the correct processor', () => {
|
||||
const processor = processorFactory(mockLogger, mockReadFilesProcessor);
|
||||
expect(processor.$runBefore).toEqual(['rendering-docs']);
|
||||
});
|
||||
|
||||
it('should ignore internal and private exports', () => {
|
||||
const processor = processorFactory(mockLogger, mockReadFilesProcessor);
|
||||
const docs = [
|
||||
{ docType: 'class', name: 'PublicExport' },
|
||||
{ docType: 'class', name: 'PrivateExport', privateExport: true },
|
||||
{ docType: 'class', name: 'InternalExport', internal: true }
|
||||
];
|
||||
processor.$process(docs);
|
||||
expect(docs[docs.length - 1].data).toEqual([
|
||||
jasmine.objectContaining({ title: 'PublicExport', type: 'class'})
|
||||
]);
|
||||
});
|
||||
});
|
||||
@ -1,13 +0,0 @@
|
||||
module.exports = function markBarredODocsAsPrivate() {
|
||||
return {
|
||||
$runAfter: ['readTypeScriptModules'],
|
||||
$runBefore: ['adding-extra-docs'],
|
||||
$process: function(docs) {
|
||||
docs.forEach(doc => {
|
||||
if (doc.name && doc.name.indexOf('ɵ') === 0) {
|
||||
doc.privateExport = true;
|
||||
}
|
||||
});
|
||||
}
|
||||
};
|
||||
};
|
||||
@ -1,28 +0,0 @@
|
||||
const testPackage = require('../../helpers/test-package');
|
||||
const processorFactory = require('./markBarredODocsAsPrivate');
|
||||
const Dgeni = require('dgeni');
|
||||
|
||||
describe('generateApiListDoc processor', () => {
|
||||
|
||||
it('should be available on the injector', () => {
|
||||
const dgeni = new Dgeni([testPackage('angular.io-package')]);
|
||||
const injector = dgeni.configureInjector();
|
||||
const processor = injector.get('markBarredODocsAsPrivate');
|
||||
expect(processor.$process).toBeDefined();
|
||||
expect(processor.$runAfter).toContain('readTypeScriptModules');
|
||||
expect(processor.$runBefore).toContain('adding-extra-docs');
|
||||
});
|
||||
|
||||
it('should mark docs starting with barred-o ɵ as private', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{ name: 'ɵPrivate' },
|
||||
{ name: 'public' }
|
||||
];
|
||||
processor.$process(docs);
|
||||
|
||||
expect(docs[0].privateExport).toBeTruthy();
|
||||
expect(docs[1].privateExport).toBeFalsy();
|
||||
});
|
||||
});
|
||||
|
||||
@ -1,61 +0,0 @@
|
||||
var _ = require('lodash');
|
||||
|
||||
/**
|
||||
* @dgProcessor
|
||||
* @description
|
||||
*
|
||||
*/
|
||||
module.exports = function matchUpDirectiveDecoratorsProcessor() {
|
||||
|
||||
return {
|
||||
$runAfter: ['ids-computed', 'paths-computed'],
|
||||
$runBefore: ['rendering-docs'],
|
||||
decoratorMappings: {'Inputs': 'inputs', 'Outputs': 'outputs'},
|
||||
$process: function(docs) {
|
||||
var decoratorMappings = this.decoratorMappings;
|
||||
_.forEach(docs, function(doc) {
|
||||
if (doc.docType === 'directive') {
|
||||
doc.selector = doc.directiveOptions.selector;
|
||||
|
||||
for (let decoratorName in decoratorMappings) {
|
||||
var propertyName = decoratorMappings[decoratorName];
|
||||
doc[propertyName] =
|
||||
getDecoratorValues(doc.directiveOptions[propertyName], decoratorName, doc.members);
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
};
|
||||
};
|
||||
|
||||
function getDecoratorValues(classDecoratorValues, memberDecoratorName, members) {
|
||||
var decoratorValues = {};
|
||||
|
||||
// Parse the class decorator
|
||||
_.forEach(classDecoratorValues, function(option) {
|
||||
// Options are of the form: "propName : bindingName" (bindingName is optional)
|
||||
var optionPair = option.split(':');
|
||||
var propertyName = optionPair.shift().trim();
|
||||
var bindingName = (optionPair.shift() || '').trim() || propertyName;
|
||||
|
||||
decoratorValues[propertyName] = {propertyName: propertyName, bindingName: bindingName};
|
||||
});
|
||||
|
||||
_.forEach(members, function(member) {
|
||||
_.forEach(member.decorators, function(decorator) {
|
||||
if (decorator.name === memberDecoratorName) {
|
||||
decoratorValues[member.name] = {
|
||||
propertyName: member.name,
|
||||
bindingName: decorator.arguments[0] || member.name
|
||||
};
|
||||
}
|
||||
});
|
||||
if (decoratorValues[member.name]) {
|
||||
decoratorValues[member.name].memberDoc = member;
|
||||
}
|
||||
});
|
||||
|
||||
if (Object.keys(decoratorValues).length) {
|
||||
return decoratorValues;
|
||||
}
|
||||
}
|
||||
@ -1,81 +0,0 @@
|
||||
module.exports = function mergeDecoratorDocs(log) {
|
||||
return {
|
||||
$runAfter: ['processing-docs'],
|
||||
$runBefore: ['docs-processed'],
|
||||
makeDecoratorCalls: [
|
||||
{type: '', description: 'toplevel'},
|
||||
{type: 'Prop', description: 'property'},
|
||||
{type: 'Param', description: 'parameter'},
|
||||
],
|
||||
$process: function(docs) {
|
||||
|
||||
var makeDecoratorCalls = this.makeDecoratorCalls;
|
||||
var docsToMerge = Object.create(null);
|
||||
|
||||
docs.forEach(function(doc) {
|
||||
|
||||
makeDecoratorCalls.forEach(function(call) {
|
||||
// find all the decorators, signified by a call to `makeDecorator(metadata)`
|
||||
var makeDecorator = getMakeDecoratorCall(doc, call.type);
|
||||
if (makeDecorator) {
|
||||
log.debug('mergeDecoratorDocs: found decorator', doc.docType, doc.name);
|
||||
doc.docType = 'decorator';
|
||||
doc.decoratorLocation = call.description;
|
||||
// get the type of the decorator metadata
|
||||
doc.decoratorType = makeDecorator.arguments[0].text;
|
||||
// clear the symbol type named (e.g. ComponentMetadataFactory) since it is not needed
|
||||
doc.symbolTypeName = undefined;
|
||||
|
||||
// keep track of the names of the docs that need to be merged into this decorator doc
|
||||
docsToMerge[doc.name + 'Decorator'] = doc;
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
// merge the metadata docs into the decorator docs
|
||||
docs = docs.filter(function(doc) {
|
||||
if (docsToMerge[doc.name]) {
|
||||
var decoratorDoc = docsToMerge[doc.name];
|
||||
log.debug(
|
||||
'mergeDecoratorDocs: merging', doc.name, 'into', decoratorDoc.name,
|
||||
doc.callMember.description.substring(0, 50));
|
||||
decoratorDoc.description = doc.callMember.description;
|
||||
|
||||
// remove doc from its module doc's exports
|
||||
doc.moduleDoc.exports =
|
||||
doc.moduleDoc.exports.filter(function(exportDoc) { return exportDoc !== doc; });
|
||||
|
||||
|
||||
// remove from the overall list of docs to be rendered
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
});
|
||||
}
|
||||
};
|
||||
};
|
||||
|
||||
function getMakeDecoratorCall(doc, type) {
|
||||
var makeDecoratorFnName = 'make' + (type || '') + 'Decorator';
|
||||
|
||||
var initializer = doc.exportSymbol && doc.exportSymbol.valueDeclaration &&
|
||||
doc.exportSymbol.valueDeclaration.initializer;
|
||||
|
||||
if (initializer) {
|
||||
// There appear to be two forms of initializer:
|
||||
// export var Injectable: InjectableFactory =
|
||||
// <InjectableFactory>makeDecorator(InjectableMetadata);
|
||||
// and
|
||||
// export var RouteConfig: (configs: RouteDefinition[]) => ClassDecorator =
|
||||
// makeDecorator(RouteConfigAnnotation);
|
||||
// In the first case, the type assertion `<InjectableFactory>` causes the AST to contain an
|
||||
// extra level of expression
|
||||
// to hold the new type of the expression.
|
||||
if (initializer.expression && initializer.expression.expression) {
|
||||
initializer = initializer.expression;
|
||||
}
|
||||
if (initializer.expression && initializer.expression.text === makeDecoratorFnName) {
|
||||
return initializer;
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -1,57 +0,0 @@
|
||||
var testPackage = require('../../helpers/test-package');
|
||||
var Dgeni = require('dgeni');
|
||||
|
||||
describe('mergeDecoratorDocs processor', function() {
|
||||
var dgeni, injector, processor, decoratorDoc, decoratorDocWithTypeAssertion, otherDoc;
|
||||
|
||||
beforeEach(function() {
|
||||
dgeni = new Dgeni([testPackage('angular.io-package')]);
|
||||
injector = dgeni.configureInjector();
|
||||
processor = injector.get('mergeDecoratorDocs');
|
||||
|
||||
decoratorDoc = {
|
||||
name: 'X',
|
||||
docType: 'var',
|
||||
exportSymbol: {
|
||||
valueDeclaration:
|
||||
{initializer: {expression: {text: 'makeDecorator'}, arguments: [{text: 'X'}]}}
|
||||
}
|
||||
};
|
||||
|
||||
decoratorDocWithTypeAssertion = {
|
||||
name: 'Y',
|
||||
docType: 'var',
|
||||
exportSymbol: {
|
||||
valueDeclaration: {
|
||||
initializer: {
|
||||
expression:
|
||||
{type: {}, expression: {text: 'makeDecorator'}, arguments: [{text: 'Y'}]}
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
otherDoc = {
|
||||
name: 'Y',
|
||||
docType: 'var',
|
||||
exportSymbol: {
|
||||
valueDeclaration:
|
||||
{initializer: {expression: {text: 'otherCall'}, arguments: [{text: 'param1'}]}}
|
||||
}
|
||||
};
|
||||
});
|
||||
|
||||
|
||||
it('should change the docType of only the docs that are initialied by a call to makeDecorator',
|
||||
function() {
|
||||
processor.$process([decoratorDoc, decoratorDocWithTypeAssertion, otherDoc]);
|
||||
expect(decoratorDoc.docType).toEqual('decorator');
|
||||
expect(decoratorDocWithTypeAssertion.docType).toEqual('decorator');
|
||||
expect(otherDoc.docType).toEqual('var');
|
||||
});
|
||||
|
||||
it('should extract the "type" of the decorator meta data', function() {
|
||||
processor.$process([decoratorDoc, decoratorDocWithTypeAssertion, otherDoc]);
|
||||
expect(decoratorDoc.decoratorType).toEqual('X');
|
||||
expect(decoratorDocWithTypeAssertion.decoratorType).toEqual('Y');
|
||||
});
|
||||
});
|
||||
@ -1,19 +0,0 @@
|
||||
/**
|
||||
* Read in JSON files
|
||||
*/
|
||||
module.exports = function jsonFileReader() {
|
||||
return {
|
||||
name: 'jsonFileReader',
|
||||
getDocs: function(fileInfo) {
|
||||
|
||||
// We return a single element array because content files only contain one document
|
||||
return [{
|
||||
docType: fileInfo.baseName + '-json',
|
||||
data: JSON.parse(fileInfo.content),
|
||||
template: 'json-doc.template.json',
|
||||
id: fileInfo.baseName,
|
||||
aliases: [fileInfo.baseName, fileInfo.relativePath]
|
||||
}];
|
||||
}
|
||||
};
|
||||
};
|
||||
@ -1,62 +0,0 @@
|
||||
module.exports = function() {
|
||||
// var MIXIN_PATTERN = /\S*\+\S*\(.*/;
|
||||
return {
|
||||
name: 'indentForMarkdown',
|
||||
process: function(str, width) {
|
||||
if (str == null || str.length === 0) {
|
||||
return '';
|
||||
}
|
||||
width = width || 4;
|
||||
|
||||
var lines = str.split('\n');
|
||||
var newLines = [];
|
||||
var sp = spaces(width);
|
||||
var spMixin = spaces(width - 2);
|
||||
var isAfterMarkdownTag = true;
|
||||
lines.forEach(function(line) {
|
||||
// indent lines that match mixin pattern by 2 less than specified width
|
||||
if (line.indexOf('{@example') >= 0) {
|
||||
if (isAfterMarkdownTag) {
|
||||
// happens if example follows example
|
||||
if (newLines.length > 0) {
|
||||
newLines.pop();
|
||||
} else {
|
||||
// wierd case - first expression in str is an @example
|
||||
// in this case the :marked appear above the str passed in,
|
||||
// so we need to put 'something' into the markdown tag.
|
||||
newLines.push(sp + '.'); // '.' is a dummy char
|
||||
}
|
||||
}
|
||||
newLines.push(spMixin + line);
|
||||
// after a mixin line we need to reenter markdown.
|
||||
newLines.push(spMixin + ':marked');
|
||||
isAfterMarkdownTag = true;
|
||||
} else {
|
||||
if ((!isAfterMarkdownTag) || (line.trim().length > 0)) {
|
||||
newLines.push(sp + line);
|
||||
isAfterMarkdownTag = false;
|
||||
}
|
||||
}
|
||||
});
|
||||
if (isAfterMarkdownTag) {
|
||||
if (newLines.length > 0) {
|
||||
// if last line is a markdown tag remove it.
|
||||
newLines.pop();
|
||||
}
|
||||
}
|
||||
// force character to be a newLine.
|
||||
if (newLines.length > 0) newLines.push('');
|
||||
var res = newLines.join('\n');
|
||||
return res;
|
||||
}
|
||||
};
|
||||
|
||||
function spaces(n) {
|
||||
var str = '';
|
||||
for (var i = 0; i < n; i++) {
|
||||
str += ' ';
|
||||
}
|
||||
return str;
|
||||
}
|
||||
|
||||
};
|
||||
@ -1,6 +0,0 @@
|
||||
module.exports = function toId() {
|
||||
return {
|
||||
name: 'toId',
|
||||
process: function(str) { return str.replace(/[^(a-z)(A-Z)(0-9)._-]/g, '-'); }
|
||||
};
|
||||
};
|
||||
@ -1,14 +0,0 @@
|
||||
var factory = require('./toId');
|
||||
|
||||
describe('toId filter', function() {
|
||||
var filter;
|
||||
|
||||
beforeEach(function() { filter = factory(); });
|
||||
|
||||
it('should be called "toId"', function() { expect(filter.name).toEqual('toId'); });
|
||||
|
||||
it('should convert a string to make it appropriate for use as an HTML id', function() {
|
||||
expect(filter.process('This is a big string with €bad#characaters¢\nAnd even NewLines'))
|
||||
.toEqual('This-is-a-big-string-with--bad-characaters--And-even-NewLines');
|
||||
});
|
||||
});
|
||||
@ -1,15 +0,0 @@
|
||||
module.exports = function() {
|
||||
return {
|
||||
name: 'trimBlankLines',
|
||||
process: function(str) {
|
||||
var lines = str.split(/\r?\n/);
|
||||
while (lines.length && (lines[0].trim() === '')) {
|
||||
lines.shift();
|
||||
}
|
||||
while (lines.length && (lines[lines.length - 1].trim() === '')) {
|
||||
lines.pop();
|
||||
}
|
||||
return lines.join('\n');
|
||||
}
|
||||
};
|
||||
};
|
||||
@ -1,15 +0,0 @@
|
||||
var factory = require('./trimBlankLines');
|
||||
|
||||
describe('trimBlankLines filter', function() {
|
||||
var filter;
|
||||
|
||||
beforeEach(function() { filter = factory(); });
|
||||
|
||||
it('should be called "trimBlankLines"',
|
||||
function() { expect(filter.name).toEqual('trimBlankLines'); });
|
||||
|
||||
it('should remove empty lines from the start and end of the string', function() {
|
||||
expect(filter.process('\n \n\nsome text\n \nmore text\n \n'))
|
||||
.toEqual('some text\n \nmore text');
|
||||
});
|
||||
});
|
||||
@ -1,5 +0,0 @@
|
||||
const {cp} = require('shelljs');
|
||||
|
||||
module.exports = function copyFolder() {
|
||||
return (from, to) => cp('-rf', from, to);
|
||||
};
|
||||
@ -1,4 +0,0 @@
|
||||
// A ts2dart compiler annotation that can be ignored in API docs.
|
||||
module.exports = function() {
|
||||
return {name: 'Annotation', ignore: true};
|
||||
};
|
||||
@ -1,3 +0,0 @@
|
||||
module.exports = function() {
|
||||
return {name: 'deprecated'};
|
||||
};
|
||||
@ -1,3 +0,0 @@
|
||||
module.exports = function() {
|
||||
return {name: 'docsNotRequired'};
|
||||
};
|
||||
@ -1,3 +0,0 @@
|
||||
module.exports = function() {
|
||||
return {name: 'experimental'};
|
||||
};
|
||||
@ -1,3 +0,0 @@
|
||||
module.exports = function() {
|
||||
return {name: 'howToUse'};
|
||||
};
|
||||
@ -1,5 +0,0 @@
|
||||
module.exports = function() {
|
||||
return {
|
||||
name: 'internal', transforms: function() { return true; }
|
||||
};
|
||||
};
|
||||
@ -1,3 +0,0 @@
|
||||
module.exports = function() {
|
||||
return {name: 'ngModule'};
|
||||
};
|
||||
@ -1,3 +0,0 @@
|
||||
module.exports = function() {
|
||||
return {name: 'noDescription', transforms: function() { return true; }};
|
||||
};
|
||||
@ -1,3 +0,0 @@
|
||||
module.exports = function() {
|
||||
return {name: 'security'};
|
||||
};
|
||||
@ -1,3 +0,0 @@
|
||||
module.exports = function() {
|
||||
return {name: 'stable'};
|
||||
};
|
||||
@ -1,3 +0,0 @@
|
||||
module.exports = function() {
|
||||
return {name: 'suppress'};
|
||||
};
|
||||
@ -1,3 +0,0 @@
|
||||
module.exports = function() {
|
||||
return {name: 'syntax'};
|
||||
};
|
||||
@ -1,4 +0,0 @@
|
||||
// A ts2dart compiler annotation that can be ignored in API docs.
|
||||
module.exports = function() {
|
||||
return {name: 'ts2dart_const', ignore: true};
|
||||
};
|
||||
@ -1,3 +0,0 @@
|
||||
module.exports = function() {
|
||||
return {name: 'whatItDoes'};
|
||||
};
|
||||
Reference in New Issue
Block a user