Invoke typedoc to produce browsable JS API documentation #4757
Conversation
niloc132
added
documentation
|
There are also a few javadoc changes to both test out features we expect to work now in typedoc, and also to work around deliberate shortcomings in typedoc (unclosed tags in a member's documentation can interrupt navigational aspects of the page). I'll cherry-pick and land those as their own branches, but for the time being they are included here to ensure that the rest of the branch is working correctly. |
niloc132
requested review from
JamesXNelson,
mofojed and
rcaudy
as code owners
| with: | ||
| switches: -avzr --delete | ||
| path: web/client-api/docs/build/documentation/ | ||
| remote_path: deephaven-core/client-api/javascript/ |
There was a problem hiding this comment.
Not sure if remote path needs to exist before this job is run, just FYI. Obv sync expectations w/ deephaven.io.
There was a problem hiding this comment.
I'm not following - how could this be omitted, where would the CI job rsync the data to?
There was a problem hiding this comment.
Sorry - didn't mean to imply you don't need to set remote_path. I'm not sure if the physical "remote path" needs to exist or not before this job will succeed. Just commenting on the fact that there is some coordination w/ deephaven.io that will be necessary.
There was a problem hiding this comment.
Ok, will verify with docs team.
There was a problem hiding this comment.
Do we have a ticket for this in the docs repo?
There was a problem hiding this comment.
Running it creates the folder, nothing needs to be done. You should create a ticket to add a link in the sidebar back to this though once it merges though
There was a problem hiding this comment.
I will do that in a few minutes after seeing if I broke main...
| :root { | ||
| --dark-color-background: #040427; | ||
| --dark-color-background-secondary: #0d1b37; | ||
| --dark-color-background-warning: #fffbef; |
There was a problem hiding this comment.
Where are these colours coming from? This one in particular I can't see referenced anywhere else in the code base.
Pretty sure we should match the colours from other docs (defined in root.scss). @dsmmcken ?
…s+rsync" This reverts commit 0950b0f.
pete-petey
modified the milestones:
October 2023,
2023 tickets that need to be 'milestone-ed' and assigned
Replaces the annotation processor previously used with a doclet implementation. This still emits a
.d.tsfile using Java mirror/element types for accurate type information, but now is able to traverse Javadoc trees as well, and produces corresponding typedoc tags or markdown.Additionally, this branch produces a tarball suitable for deployment as an npm module, containing only those generated types. However, this output is still untested.
CI is updated to deploy the results of this to https://deephaven.io/core/client-api/javascript/.
This branch is a draft, but the results of this can currently be seen at https://colinalworth.com/documentation/.