Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Can't generate documentation #1259

Closed
TheModMaker opened this issue Jan 29, 2018 · 5 comments
Closed

Can't generate documentation #1259

TheModMaker opened this issue Jan 29, 2018 · 5 comments
Assignees
@joeyparrish
Labels
flag: Why didn't we catch this sooner This issue is embarassing; we may still need an automated test that could have prevented this issue status: archived Archived and locked; will not be updated type: bug Something isn't working correctly
Milestone
v2.4

Comments

@TheModMaker
Copy link
Contributor

Trying to generate documentation using build/docs.py generates a large number of errors and doesn't generate anything. This seems to be caused by the new ES6 syntax. This means the nightly page no longer has the documentation page. Also, for some reason, the errors in generation don't result in a non-zero exit code, so the scripts still "succeed".
@TheModMaker TheModMaker added type: bug Something isn't working correctly flag: Why didn't we catch this sooner This issue is embarassing; we may still need an automated test that could have prevented this issue labels Jan 29, 2018
@TheModMaker TheModMaker added this to the v2.4.0 milestone Jan 29, 2018
@joeyparrish joeyparrish self-assigned this Jan 29, 2018
@joeyparrish
Copy link
Member

The latest jsdoc can parse ES6, but we would lose some of our customizations. I will investigate what it would take to unfork jsdoc. If we can, we will use jsdoc from npm instead of keeping a forked copy in the repo.

@joeyparrish
Copy link
Member

I can't find an easy way to deal with the lack of error code when the existing jsdoc fails. Executing latest jsdoc from npm, we do get a non-zero error code when it fails.

@joeyparrish
Copy link
Member

Good news: new jsdoc is WAY faster. On my workstation, building the docs went from about 35s with the old tools to about 5s with the new tools. 7x faster.

@joeyparrish
Copy link
Member

Some of the code which triggers this has been cherry-picked to v2.3.x and must be patched up in that branch. Otherwise, this issue will block v2.3.x releases.

joeyparrish added a commit that referenced this issue Jan 30, 2018
@joeyparrish
Undo some ES6 arrow functions
e0ce4b8 
Releases from v2.3.x are being impeded by #1259, in which our old fork
of jsdoc breaks on ES6 arrow functions.  To unblock a bugfix release,
the ES6 arrow functions introduced in lib/offline/ have been converted
back to ES5 anonymous functions.
shaka-bot pushed a commit that referenced this issue Jan 31, 2018
@joeyparrish
Upgrade and unfork jsdoc
ed54199 
This updates jsdoc to the latest version from npm and forks a copy of
the default jsdoc template.

In subsequent commits, we will reapply our customizations to the
template and to a jsdoc plugin.

This also fixes several bad annotations that the new jsdoc failed to
parse.

Issue #1259

Change-Id: I00a47270ea4754e1c96c43ca900d5cf889ab72e6
shaka-bot pushed a commit that referenced this issue Jan 31, 2018
@joeyparrish
Customize jsdoc nav order
5bd6a80 
We can now specify in a config file what order the nav elements should
be in, and which nav elements should appear.

Issue #1259

Change-Id: I4caa3a0585b4140e76a66f1c5bed0c20c82ca5a4
shaka-bot pushed a commit that referenced this issue Jan 31, 2018
@joeyparrish
Use long names in all jsdoc headers
0ed16c6 
For example, instead of "Class: Ewma", we want "Class: shaka.abr.Ewma".

Issue #1259

Change-Id: Id6918b508d1bde4a6b3be16805a63e673b58d0e4
shaka-bot pushed a commit that referenced this issue Jan 31, 2018
@joeyparrish
Add custom tag support to jsdoc
91ad9b6 
This uses a plugin to customize certain tags in jsdoc.

In some cases, we have invented new tags in our build system.
In others, we want to the docs to treat things differently than the
build.

Issue #1259

Change-Id: I934ad578cf7479572cb807c5b3aee489c332343a
shaka-bot pushed a commit that referenced this issue Jan 31, 2018
@joeyparrish
Add jsdoc output for base classes
af26b4f 
Now we can see when one class extends or inherits from another.

Issue #1259

Change-Id: I14fc6361ed6c967d87e8aa9da0fc7c12e4177faa
shaka-bot pushed a commit that referenced this issue Jan 31, 2018
@joeyparrish
Add jsdoc metadata for interface implementations
b0d6a3e 
The docs template already shows this, but for some reason, it is not
populated anywhere.  Our plugin takes care of this.

Issue #1259

Change-Id: Ifd4233e5b7b9ca5abb1aec681ae1b12c8a895d44
shaka-bot pushed a commit that referenced this issue Jan 31, 2018
@joeyparrish
Tweak jsdoc formatting
a324958 
 - always show Constructor heading for class constructors
 - hide top-level header that just repeats information from elsewhere
 - show namespace descriptions as a "class description" at the top
 - remove 2 redundant headers from tutorials that repeat the title
 - use a gray background for inline code, as github does
 - put more space between headings within a tutorial

Issue #1259

Change-Id: I7eedd69b7a732da0f3292912ec07d97eccb44eed
shaka-bot pushed a commit that referenced this issue Jan 31, 2018
@joeyparrish
Show jsdoc enum values and allow focus from URL
5f8fe9d 
We now show enum values in the generated documentation.  Further, a
URL fragment of "value:6001", for example, would highlight and scroll
directly to the row in which value 6001 is described.  This is used
by the demo app to take users directly to the appropriate docs for a
given error code.

Issue #1259

Change-Id: Iae47e661db2bba43eb16a4f3fd1476adea59aecb
shaka-bot pushed a commit that referenced this issue Jan 31, 2018
@joeyparrish
Add linksource tag to jsdoc
df0d34c 
This is a customization that allows us to link to the source code of
a thing, rather than its documentation.

Redoing this in a clean way caught some bad links, which have now been
fixed.

Issue #1259

Change-Id: I4c63aa10ddad8f8f21b224668c3529c70a1c6756
joeyparrish added a commit that referenced this issue Feb 1, 2018
@joeyparrish
Fix some bad annotations
c918dc2 
Discovered during the jsdoc transition (#1259) and backported to v2.3.x
joeyparrish added a commit that referenced this issue Feb 1, 2018
@joeyparrish
Fix one more bad annotation
ec43d49 
Discovered during the jsdoc transition (#1259) and backported to v2.3.x
@joeyparrish joeyparrish mentioned this issue Feb 1, 2018
Open
shaka-bot pushed a commit that referenced this issue Feb 1, 2018
@joeyparrish
Allow the user to show/hide parts of the docs
c2472dc 
This adds custom CSS classes and a widget to show/hide various parts
of the docs.  By default, we show exported interfaces only.  The user
can also select "public" (all public interfaces, even those not
exported), and "everything" (even private members).

Issue #1259

Change-Id: Iff8f4d84658a3d19ad8f2f979ab37b256393589f
shaka-bot pushed a commit that referenced this issue Feb 1, 2018
@joeyparrish
Show more verbose functions and records in docs
75d9767 
Replace generic "function" and "record" types with their original types.
With this, we see, for example:
   "function(string):number" instead of just "function"
   "{{ foo: string, bar: number }}" instead of just "Object"

Issue #1259

Change-Id: Icd5ddbacadb7ec799e025b67f311792dd590b310
shaka-bot pushed a commit that referenced this issue Feb 1, 2018
@joeyparrish
Improve annotations and docs for TtmlTextParser
14d91b0 
During docs review, I noticed that shaka.text.TtmlTextParser's
textAlignToLineAlign_ was defined as merely {Object}.  Improving that
to {Object.<string, string>} caused compiler issues, so I had to
further refine to {Object.<string, shaka.text.Cue.lineAlign>} and
refer to the enum values instead of directly using strings.

Issue #1259

Change-Id: Ifb012771a534f74f4458f8673fd4d12d136b2638
shaka-bot pushed a commit that referenced this issue Feb 1, 2018
@joeyparrish
Improve annotations and docs for PublicPromise
fe2eba5 
During docs review, I noticed that resolve and reject on PublicPromise
were documented as fields rather than as methods.  This redefines the
types of resolve and reject so that they show up as proper methods.

Issue #1259

Change-Id: I0b7e22f9f1edf7d8ba15362306c55d7cdbd32e76
shaka-bot pushed a commit that referenced this issue Feb 1, 2018
@joeyparrish
Fix jsdoc linksource error on bad markdown escape
3dbf28c 
Issue #1259

Change-Id: I34fb3514b04087fb1389f64e3cb91eaf852af648
joeyparrish added a commit that referenced this issue Feb 12, 2018
@joeyparrish
Fix jsdoc linksource error on bad markdown escape
e74255c 
Issue #1259

Change-Id: I34fb3514b04087fb1389f64e3cb91eaf852af648
joeyparrish added a commit that referenced this issue Mar 26, 2018
@joeyparrish
Upgrade and unfork jsdoc
0edac1c 
This updates jsdoc to the latest version from npm and forks a copy of
the default jsdoc template.

In subsequent commits, we will reapply our customizations to the
template and to a jsdoc plugin.

This also fixes several bad annotations that the new jsdoc failed to
parse.

Backported to v2.3.x

Issue #1259

Change-Id: I00a47270ea4754e1c96c43ca900d5cf889ab72e6
joeyparrish added a commit that referenced this issue Mar 26, 2018
@joeyparrish
Customize jsdoc nav order
355213f 
We can now specify in a config file what order the nav elements should
be in, and which nav elements should appear.

Issue #1259

Change-Id: I4caa3a0585b4140e76a66f1c5bed0c20c82ca5a4
joeyparrish added a commit that referenced this issue Mar 26, 2018
@joeyparrish
Use long names in all jsdoc headers
ae7cc89 
For example, instead of "Class: Ewma", we want "Class: shaka.abr.Ewma".

Issue #1259

Change-Id: Id6918b508d1bde4a6b3be16805a63e673b58d0e4
joeyparrish added a commit that referenced this issue Mar 26, 2018
@joeyparrish
Add custom tag support to jsdoc
1231cab 
This uses a plugin to customize certain tags in jsdoc.

In some cases, we have invented new tags in our build system.
In others, we want to the docs to treat things differently than the
build.

Issue #1259

Change-Id: I934ad578cf7479572cb807c5b3aee489c332343a
joeyparrish added a commit that referenced this issue Mar 26, 2018
@joeyparrish
Add jsdoc output for base classes
bc655c8 
Now we can see when one class extends or inherits from another.

Issue #1259

Change-Id: I14fc6361ed6c967d87e8aa9da0fc7c12e4177faa
joeyparrish added a commit that referenced this issue Mar 26, 2018
@joeyparrish
Add jsdoc metadata for interface implementations
630c502 
The docs template already shows this, but for some reason, it is not
populated anywhere.  Our plugin takes care of this.

Issue #1259

Change-Id: Ifd4233e5b7b9ca5abb1aec681ae1b12c8a895d44
joeyparrish added a commit that referenced this issue Mar 26, 2018
@joeyparrish
Tweak jsdoc formatting
1f64c88 
 - always show Constructor heading for class constructors
 - hide top-level header that just repeats information from elsewhere
 - show namespace descriptions as a "class description" at the top
 - remove 2 redundant headers from tutorials that repeat the title
 - use a gray background for inline code, as github does
 - put more space between headings within a tutorial

Issue #1259

Change-Id: I7eedd69b7a732da0f3292912ec07d97eccb44eed
joeyparrish added a commit that referenced this issue Mar 26, 2018
@joeyparrish
Show jsdoc enum values and allow focus from URL
b490a17 
We now show enum values in the generated documentation.  Further, a
URL fragment of "value:6001", for example, would highlight and scroll
directly to the row in which value 6001 is described.  This is used
by the demo app to take users directly to the appropriate docs for a
given error code.

Issue #1259

Change-Id: Iae47e661db2bba43eb16a4f3fd1476adea59aecb
joeyparrish added a commit that referenced this issue Mar 26, 2018
@joeyparrish
Add linksource tag to jsdoc
9a0c778 
This is a customization that allows us to link to the source code of
a thing, rather than its documentation.

Redoing this in a clean way caught some bad links, which have now been
fixed.

Backported to v2.3.x

Issue #1259

Change-Id: I4c63aa10ddad8f8f21b224668c3529c70a1c6756
joeyparrish added a commit that referenced this issue Mar 26, 2018
@joeyparrish
Allow the user to show/hide parts of the docs
06f8b2f 
This adds custom CSS classes and a widget to show/hide various parts
of the docs.  By default, we show exported interfaces only.  The user
can also select "public" (all public interfaces, even those not
exported), and "everything" (even private members).

Issue #1259

Change-Id: Iff8f4d84658a3d19ad8f2f979ab37b256393589f
joeyparrish added a commit that referenced this issue Mar 26, 2018
@joeyparrish
Show more verbose functions and records in docs
49b940b 
Replace generic "function" and "record" types with their original types.
With this, we see, for example:
   "function(string):number" instead of just "function"
   "{{ foo: string, bar: number }}" instead of just "Object"

Issue #1259

Change-Id: Icd5ddbacadb7ec799e025b67f311792dd590b310
joeyparrish added a commit that referenced this issue Mar 26, 2018
@joeyparrish
Sort jsdoc tutorials according to the config file
0359e45 
This feature is based on a forked version of jsdoc which we hope to
land jsdoc/jsdoc#1502 upstream.

Closes #1259

Change-Id: I48e07ffd8ae9fc2c07cd48b3e02b85e87694d341
@joeyparrish
Copy link
Member

All fixes for this issue have now been cherry-picked to v2.3.x, to facilitate the cherry-picking of other changes (which use ES6) to v2.3.x.

@shaka-project shaka-project locked and limited conversation to collaborators Apr 3, 2018
@shaka-bot shaka-bot added the status: archived Archived and locked; will not be updated label Apr 15, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@joeyparrish joeyparrish

Labels
flag: Why didn't we catch this sooner This issue is embarassing; we may still need an automated test that could have prevented this issue status: archived Archived and locked; will not be updated type: bug Something isn't working correctly
Projects
None yet
Milestone
v2.4
Development

No branches or pull requests
3 participants
@TheModMaker @joeyparrish @shaka-bot