Convert default themes to JSX; merge into typedoc repo #1634

cspotcode · 2021-07-18T04:45:56Z

Replacing TypeStrong/typedoc-default-themes#137

EDIT next tasks to get this PR ready to merge:

Future work

Not necessary in this PR, but it's nice to get excited about future possibilities:

deduplicate all the token <spans>: {, [, ], etc.
remove all redundant <></> fragment wrappers, {} wrappers, etc.

tsconfig.json

cspotcode · 2021-07-24T08:16:33Z

src/lib/models/reflections/abstract.ts

@@ -216,6 +216,10 @@ export class ReflectionFlags extends Array<string> {
        return this.hasFlag(ReflectionFlag.Readonly);
    }

+    get isExported() {
+        return TODO as boolean;
+    }


This was being called from templates but not declared anywhere. Do you know what the implementation should be?

This was removed in 0.20, it's always true now.

cspotcode · 2021-07-27T22:52:26Z

It works! Tests have been (temporarily) updated to emit prettified versions of both the spec html and the typedoc output for visual inspection. These outputs match:

https://github.com/cspotcode/typedoc/compare/jsx-progress-report/expected..cspotcode:jsx-progress-report/actual

Next I'm going to render the spec output from master and from this pull request, and use a visual inspection tool to check for differences.

cspotcode · 2021-07-27T23:21:45Z

Notes about this PR:

it is currently taking the expected and the actual html and formatting both with prettier and some find-and-replace. We'll need to remove that and replace all the specs prior to merging this. Tests run way slower doing this postprocessing.

In a handful of places, markdown is wrapped in an <md> element. We'll need to change that to a <div>.

cspotcode · 2021-07-27T23:35:28Z

Also need to figure out how and when the webpack configs run; wire them into the build.

cspotcode · 2021-07-28T00:15:19Z

TODO use osnap instead of percy for visual testing

cspotcode · 2021-07-28T03:53:30Z

Added scripts for visual regression testing. Pushed the generated report here: https://github.com/cspotcode/typedoc/tree/jsx-visual-regression-report

Capture screenshots of master build of ./dist/tmp/test

Not explained here, but basically modify and then run the ./src/test/capture-screenshots.ts. Modify it to capture the output of master ./dist/tmp/test, wherever that is on your filesystem

Copy those screenshots to ./dist/tmp/.reg/expected

This might do the trick: npm run test:visual-regression-report:copy-actual-to-expected

Now run tests of this branch and generate a comparison report

npm run build
PRESERVE_OUTPUT_FOR_VISUAL_REGRESSION_TEST=true npm test
npm run test:visual-regression-report

Open dist/tmp/.reg/index.html to view the report UI

cspotcode · 2021-07-28T13:11:46Z

I updated the op with a checklist of tasks.

…its with wrapper div

Gerrit0

decide where theme source assets should live, currently in /src/lib/output/themes/
decide where built theme assets should live, currently in /dist/lib/output/themes/bin

I'm fine with this, can always change later... not a public path.

they are only used when logging an error message: can we remove the info from the message?

I think it is still useful, will likely be moving eventually once I get around to creating a proper comment parser that's a bit smarter than regex.

fix isExported to match review feedback?

Likely just going to end up removing this

Gerrit0 · 2021-07-31T02:05:35Z

src/lib/output/themes/MarkedPlugin.ts

-                    } else {
-                        return contents;
-                    }
+                    // if (path.substr(-4).toLocaleLowerCase() === ".hbs") {


Gerrit0 · 2021-07-31T02:26:03Z

tsconfig.json

@@ -1,7 +1,7 @@
 {
    "compilerOptions": {
        "module": "CommonJS",
-        "lib": ["ES2018"],
+        "lib": ["ES2018", "dom"],


Hoping to avoid needing to do this... probably time typedoc started using project references. The themes have dom, but not typedoc itself.

Does it make sense to publish the themes as separate packages with a simple monorepo setup? It would make the themes more clearly look like how a third-party theme might be implemented.

Gerrit0 · 2021-07-31T02:28:42Z

src/test/converter/react/react.tsx

@@ -8,8 +8,10 @@ export interface DemoProps {
 export class Demo {
    private foo: number;

+    //@ts-ignore


I think it was complaining that props is never used. I could add the same this.foo trick for this.props

cspotcode

they are only used when logging an error message: can we remove the info from the message?

I think it is still useful, will likely be moving eventually once I get around to creating a proper comment parser that's a bit smarter than regex.

Ok, might need to refactor DefaultThemeRenderContext a bit. The current implementation uses a singleton RenderContext for each page, but we can instead create a new RenderContext for every page, so that the RenderContext has information about the page -- maybe a reference to the PageEvent? -- which it can expose to the partials.

If we're going to create a new RenderContext for each page, then we can reduce the work being done in the constructor. Instead of each partial being a factory wrapper around the partial -- (bindings: Bindings) => (reflection: Reflection) => <> -- we can simplify to a single function which accepts both bindings and reflection.

I had thought of inlining all partials as methods of the RenderContext, but I feel like splitting into separate files is easier to follow. I dunno, I'm not sure which is better.

cspotcode · 2021-07-31T06:48:57Z

src/test/converter/react/react.tsx

@@ -8,8 +8,10 @@ export interface DemoProps {
 export class Demo {
    private foo: number;

+    //@ts-ignore


I think it was complaining that props is never used. I could add the same this.foo trick for this.props

Gerrit0 · 2021-09-10T19:00:18Z

I'm rather confused as to why GitHub didn't pick this up as merged, it's been merged and now released as 0.22.0! Thanks again :)

cspotcode added 2 commits July 18, 2021 00:14

add jsx templates WIP

1f2b08d

WIP

98f3858

cspotcode marked this pull request as draft July 18, 2021 04:46

Gerrit0 reviewed Jul 18, 2021

View reviewed changes

tsconfig.json Outdated Show resolved Hide resolved

cspotcode added 2 commits July 18, 2021 21:58

WIP

de07445

whole lotta WIP

308f31b

cspotcode commented Jul 24, 2021

View reviewed changes

cspotcode added 16 commits July 24, 2021 04:32

way more WIP

4b1c7fe

more WIP

93a5749

WIP

71938cb

WIP

e6283bb

wip

5145323

wip

d941bd3

wip

2be9f65

wip

c040fd8

wip

9b477d8

wip

b975fdc

spec updates

1642f9f

update specs

be193d6

wip

2346df0

WIP

71c1325

wip

d148cc4

it works!

e54233d

cspotcode added 2 commits July 27, 2021 18:56

fixdeps

e0c605e

fix

a18eb41

visual regression testing and misc

b6ffed6

cspotcode added 6 commits July 29, 2021 08:24

update

54b00af

AFTER THIS POINT specs are rewritten with new jsx output; markdown em…

2f836b4

…its with wrapper div

remove prettiering of html from tests

c389e59

update specs

e891efa

switch markdown <md> tag to <div>

62cf210

update specs

fab6dae

cspotcode marked this pull request as ready for review July 29, 2021 12:59

cspotcode added 4 commits July 29, 2021 09:08

update build scripts to run webpack

475ed99

fix linting

b3ea1ff

linting

1963574

Update lib.tsx

67c0421

cspotcode mentioned this pull request Jul 29, 2021

Official Github Action for zero-config publishing to GH Pages #1485

Closed

Gerrit0 reviewed Jul 31, 2021

View reviewed changes

Gerrit0 mentioned this pull request Jul 31, 2021

TypeDoc@future #1266

Closed

cspotcode commented Jul 31, 2021

View reviewed changes

Gerrit0 closed this Sep 10, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Convert default themes to JSX; merge into typedoc repo #1634

Convert default themes to JSX; merge into typedoc repo #1634

cspotcode commented Jul 18, 2021 •

edited

Loading

cspotcode Jul 24, 2021

Gerrit0 Jul 27, 2021

cspotcode commented Jul 27, 2021

cspotcode commented Jul 27, 2021 •

edited

Loading

cspotcode commented Jul 27, 2021

cspotcode commented Jul 28, 2021

cspotcode commented Jul 28, 2021 •

edited

Loading

cspotcode commented Jul 28, 2021

Gerrit0 left a comment

Gerrit0 Jul 31, 2021

Gerrit0 Jul 31, 2021

cspotcode Jul 31, 2021

Gerrit0 Jul 31, 2021

cspotcode Jul 31, 2021

cspotcode left a comment

cspotcode Jul 31, 2021

Gerrit0 commented Sep 10, 2021

Convert default themes to JSX; merge into typedoc repo #1634

Convert default themes to JSX; merge into typedoc repo #1634

Conversation

cspotcode commented Jul 18, 2021 • edited Loading

Future work

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cspotcode commented Jul 27, 2021

cspotcode commented Jul 27, 2021 • edited Loading

cspotcode commented Jul 27, 2021

cspotcode commented Jul 28, 2021

cspotcode commented Jul 28, 2021 • edited Loading

cspotcode commented Jul 28, 2021

Gerrit0 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cspotcode left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Gerrit0 commented Sep 10, 2021

cspotcode commented Jul 18, 2021 •

edited

Loading

cspotcode commented Jul 27, 2021 •

edited

Loading

cspotcode commented Jul 28, 2021 •

edited

Loading