Use plain typedoc for generating nodejs docs #10964
Conversation
julienp
force-pushed
the
julienp/use-plain-typedoc
branch
from
c7acfca
to
86407e7
Compare
julienp
force-pushed
the
julienp/use-plain-typedoc
branch
from
86407e7
to
2ff0dd6
Compare
julienp
force-pushed
the
julienp/use-plain-typedoc
branch
from
2ff0dd6
to
f74f2df
Compare
|
Somehow the link in the menu pointing to the SDK docs loses the href attribute and I have no idea why this is happening 
|
There was a problem hiding this comment.
@julienp This looks great! Added a note to get the link to work correctly.
If I wanted to make any thematic changes, how would I do that? I don't think we necessarily need to block on it, but would be good to know where to look when the time comes.
julienp
force-pushed
the
julienp/use-plain-typedoc
branch
from
f74f2df
to
3d73c3e
Compare
Thanks for the help on the link! Regarding theming the docs I see two options, we can include a CSS file via --customCss when we run typedoc, or we could create a custom theme and include that. I'd be happy to help with that work. |
|
The structure of the docs changed a bit, for example What also changed is that the index pages for each module are just that, an index, with each export of a module on a separate page. |
|
@julienp There are a bunch, yeah, and from various places (see this GitHub code search), so if we could redirect client-side without too much effort, that'd be ideal. We did something similar here after splitting a giant docs page into several: However I think this case might be a little different in that the new pages at |
julienp
force-pushed
the
julienp/use-plain-typedoc
branch
from
3d73c3e
to
6063e63
Compare
julienp
force-pushed
the
julienp/use-plain-typedoc
branch
from
6063e63
to
52107dd
Compare
|
I added client side The map redirects was gathered with a hacked up version of tscdocsgen. |
The previous docs had all the exports on a single page and we make use of #anchor links to link to the export.
julienp
force-pushed
the
julienp/use-plain-typedoc
branch
from
52107dd
to
c796e0a
Compare
|
@julienp Almost there! Looks like we just need a few redirects:
The client-side stuff seems doable in `redirects.js. For the others, we can probably create a new text file for them here, which will generate proper 301s once this goes out: https://github.com/pulumi/docs/tree/master/scripts/redirects Both should work in a PR preview as well. I'll see if I can spend a little time today setting some of this up for ya. |
|
@julienp On second thought, the traffic to these pages probably doesn't warrant doing that much more work here. Looking at the data, I think it'd be fine if we just made sure these redirected to the right place: I'll push a PR that adds those of these that still need handling in a redirects file, and then we should be good to go. We can add the client-side redirects in a follow up, but I honestly wouldn't block on it. There's enough good here to roll forward with now IMO! |
|
@julienp All right, 5995d84 adds a redirects file for the pages listed above, and replaces the If the preview looks good, I'll go ahead and merge, and we can address the anchor links in a quick follow. Thanks for making this happen! |
cnunciato
force-pushed
the
julienp/use-plain-typedoc
branch
from
5995d84
to
70ef5af
Compare
cnunciato
force-pushed
the
julienp/use-plain-typedoc
branch
from
70ef5af
to
a09e5b5
Compare
# Description Noticed a couple warnings when building the docs using typedoc. - Fix some typedoc `@param` tags - Export automation.tag.TagMap type Ref: pulumi/docs#10964 ## Checklist - [ ] I have run `make tidy` to update any new dependencies - [ ] I have run `make lint` to verify my code passes the lint check - [ ] I have formatted my code using `gofumpt` <!--- Please provide details if the checkbox below is to be left unchecked. --> - [ ] I have added tests that prove my fix is effective or that my feature works <!--- User-facing changes require a CHANGELOG entry. --> - [ ] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change <!-- If the change(s) in this PR is a modification of an existing call to the Pulumi Cloud, then the service should honor older versions of the CLI where this change would not exist. You must then bump the API version in /pkg/backend/httpstate/client/api.go, as well as add it to the service. --> - [ ] Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version <!-- @pulumi employees: If yes, you must submit corresponding changes in the service repo. -->
Proposed changes
Fixes #10964
Our custom
tsdocgentool is heavily dependant on the typescript version used in pulumi/pulumi and changes to the version cause issues.Similar to how we switched Python docs to use plain Sphinx, this moves to using plain typedoc to generate HTML (instead of our current 2 step process of typedoc generating JSON and then tsdocgen producing HTML from the).
Interesting changes are in 48e75a0
The URL structure for modules changed, there are redirects in 8601ac2
Docs for pulumi/pulumi http://www-production-pulumi-docs-origin-pr-10964-f74f2df6.s3-website.us-west-2.amazonaws.com/docs/reference/pkg/nodejs/pulumi/pulumi/
Unreleased product version (optional)
Related issues (optional)
pulumi/pulumi-hugo#4045