TypeDoc #2092
TypeDoc #2092
Conversation
There was a problem hiding this comment.
This is cool! I have some comments below, and then a general comment which is that I think it would be cool to have this documentation and the Storybook documentation hosted together, perhaps even by the main NEXT.js server, so that it can all be available on a single server (without having to run three, or even two of them).
I wonder if that could be possible by writing a custom build/start script (that we can use on Vercel) that builds Storybook and TypeDoc into the NEXT.js /public directory and then builds and starts NEXT.js. What do you think?
docs/time/time.md
Outdated
| ## Response Format | ||
|
|
||
| The Zetkin back end's resonses sometimes include dates serialized using a different format, with a `+00:00` suffix instead of the `Z` that the front end's `toISOString()` approach uses to denote the UTC timezone. For these, we use {@link removeOffset removeOffset} to strip the `+00:00` off the end. |
There was a problem hiding this comment.
While not strictly wrong, this might be a bit misleading with regards to the "philosophy" of how we use time in Zetkin. Also, both the Z and +00:00 are valid ISO 8601 time strings and that's the standard that we try to adhere to, so it shouldn't matter if it's one or the other as long as it's valid by ISO 8601 and implemented in a way that understands ISO 8601.
I don't have a lot of time right now (no pun intended) but the short version of the Zetkin philosophy on timestamps is:
- Any timestamp generated on the server (e.g. to indicate when a thing was created/updated) should be UTC
- Any timestamp generated by the user (e.g. to schedule an activity) should allow any timezone
The hacks you see in a lot of places is because of the default behavior of JS Date (always parsing in local timezone) and (1) above, because although all server-generated timestamps are indeed UTC, a lot of them do not include timezone information, so that's added in the parsing step on the frontend.
The second part of the philosophy is quite new, and the only proper implementation of (2) so far is in email scheduling, where the UI actually presents the option to pick a timezone, and (barring any bugs) that timezone is included in the ISO timestamp as an offset between -12:00 and +12:00.
| /** | ||
| * Optionally override {@link shouldLoad shouldLoad} with a custom function. | ||
| * @returns {boolean} Whether the list should be loaded. | ||
| */ |
There was a problem hiding this comment.
OMG I forgot about this. Here I am reading your documentation of my code and realizing it does things I didn't even know. 😊
src/core/caching/futures.ts
Outdated
| * ```mermaid | ||
| * flowchart TD | ||
| * A[data: null\nerror: null\nisLoading: false] | ||
| * B[data: null\nerror: null\nisLoading: true] | ||
| * C[data: null\nerror: Error\nisLoading: false] | ||
| * D[data: Object\nerror: null\nisLoading: false] | ||
| * E{Success?} | ||
| * A -->|Asynchronous operation begins| B | ||
| * B -->|Asynchronous operation ends| E | ||
| * E -->|Yes| D | ||
| * E -->|No| C | ||
| * ``` |
There was a problem hiding this comment.
I'm guessing this should render a flowchart as some sort of graphic, but I'm not sure how to run the code in a way that does. I tried yarn typedoc which did build an output into ./typedoc/ that looked like something that I should be able to serve as static files, but that didn't work. What is the right way to view this?
There was a problem hiding this comment.
An update. It seems that it was just really slow to load (note the loading duration in screenshot below), and one file failed:
After more than a minute of loading mermaid-related JS files, it finally rendered this:
Is this something that you are also experiencing or is it just me?
There was a problem hiding this comment.
Yeah not been very impressed with the reliability of typescript-plugin-mermaid tbh
|
I did a tiny experiment with my idea and it worked fine!
Here's what I did. I just tried building and running it locally, but it should also work fine on Vercel (where we run our development previews) by just changing the build command to diff --git a/.gitignore b/.gitignore
index 4cb8d8bb6..8d2b553c0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -46,4 +46,8 @@ yarn-error.log*
tsconfig.tsbuildinfo
# typedoc
-/typedoc/
\ No newline at end of file
+/typedoc/
+
+# generated docs
+public/docs
+public/storybook
diff --git a/next.config.js b/next.config.js
index 865a00036..e391413ff 100644
--- a/next.config.js
+++ b/next.config.js
@@ -12,6 +12,16 @@ module.exports = {
},
async redirects() {
return [
+ {
+ source: '/storybook',
+ destination: '/storybook/index.html',
+ permanent: true,
+ },
+ {
+ source: '/docs',
+ destination: '/docs/index.html',
+ permanent: true,
+ },
{
source: '/:prevPath*/calendar/events',
destination: '/:prevPath*/calendar',
diff --git a/package.json b/package.json
index 964649193..61fe05a1d 100644
--- a/package.json
+++ b/package.json
@@ -3,6 +3,7 @@
"version": "41.0.0",
"private": true,
"scripts": {
+ "docs:build": "storybook build --out public/storybook && typedoc --out public/docs",
"analyze": "ANALYZE=true next build",
"build": "next build",
"start": "next start -p 80",
diff --git a/tsconfig.json b/tsconfig.json
index 4750c687f..610660b5f 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -46,6 +46,8 @@
".next/types/**/*.ts"
],
"exclude": [
- "node_modules"
+ "node_modules",
+ "public/storybook",
+ "public/docs"
]
}
|
|
I'm eager to hear your thoughts on my idea of deploying to a single app (for the dev server and preview builds on Vercel). What do you think? |
|
Christ I left this to rot a while huh. I love the idea with the single deploy. What are the steps required for making this mergeable? Here's my first draft attempt at a to-do list for myself.
How's that? |
|
Love that you're back! It's been a while since I looked at this now, but I'm going to trust my previous self and assume that my last review is correct, that there are only those small changes required. The single-deploy would be nice to get in as well, but I guess that could be a separate PR! |
There was a problem hiding this comment.
Lets get this merged! I can't find anything wrong with it and the documentation is a significant improvement.
Let's still try to make a single-deploy solution which hosts typedocs, storybook and NEXT.js alongside each other, which will make deployment of the preview builds faster and cheaper.
Following up from the Slack discussion. This seems to have reached a point where it's going to move forward better as a pull request instead of just a branch. Curious about the time-related comments! Was tempted to just walk that commit back but it's worth keeping just cos I'm keen to learn more context about that!