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.

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

chore (docusaurus 3): regenerate vNext API docs #4669

Merged
merged 5 commits into from
Dec 4, 2024

Conversation

pepopowitz
Copy link
Collaborator

Description

Contributes to #4560. Feel free to merge it at your convenience @akeller; I decided I didn't want to just start dumping big commits into your PR, or wreck how you were tracking your progress.

Regenerates the API docs for vNext, for all APIs. This should help resolve markdown errors in that version.

Things this PR doesn't include, but I learned will also be necessary in the d3 conversion:

  • converting the older version specs 😭. We don't generate these; they become basically "hardcoded" when we cut each version. I think this will involve tracking down the exact spec at the time of cutting each version, each API, and hacking the regeneration process to put things in the correct place.
  • Rewrite of the DocItem/Metadata and DocCard components, which use useDoc from the base theme, which is no longer exposed to us.

When should this change go live?

  • This is a bug fix, security concern, or something that needs urgent release support.
  • This is already available but undocumented and should be released within a week.
  • This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
  • This is part of a scheduled alpha or minor. (apply alpha or minor label)
  • There is no urgency with this change and can be released at any time.

PR Checklist

  • My changes are for an already released minor and are in /versioned_docs directory.
  • My changes are for the next minor and are in /docs directory (aka /next/).

@pepopowitz pepopowitz requested a review from akeller November 26, 2024 21:26
@pepopowitz pepopowitz added the d3 Path to Docusaurus 3 label Nov 26, 2024
Copy link
Contributor

👋 🤖 🤔 Hello, @pepopowitz! Did you make your changes in all the right places?

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.6/.

  • docs/apis-tools/camunda-api-rest/sidebar-schema.js
  • docs/apis-tools/camunda-api-rest/specifications/activate-jobs.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/assign-user-task.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/broadcast-signal.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/camunda-8-rest-api.info.mdx
  • docs/apis-tools/camunda-api-rest/specifications/cancel-process-instance.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/complete-job.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/complete-user-task.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/correlate-message.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/create-deployment.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/create-document-link.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/create-document.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/create-element-instance-variables.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/create-process-instance.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/create-user.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/delete-document.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/delete-resource.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/evaluate-decision.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/fail-job.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/find-authorizations.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/find-decision-definitions.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/find-decision-instances.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/find-decision-requirements.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/find-flow-node-instances.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/find-incidents.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/find-process-definitions.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/find-process-instances.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/find-user-authorizations.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/find-user-task-variables.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/find-user-tasks.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/find-users.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/find-variables.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-decision-definition-xml.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-decision-definition.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-decision-instance.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-decision-requirements-xml.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-decision-requirements.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-document.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-flow-node-instance.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-incident.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-license.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-process-definition-xml.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-process-definition.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-process-instance.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-start-process-form.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-topology.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-user-task-form.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-user-task.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/get-variable.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/migrate-process-instance.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/modify-process-instance.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/pin-clock.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/publish-message.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/report-job-error.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/reset-clock.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/resolve-incident.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/sidebar.js
  • docs/apis-tools/camunda-api-rest/specifications/sidebar.ts
  • docs/apis-tools/camunda-api-rest/specifications/unassign-user-task.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/update-authorization.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/update-job.api.mdx
  • docs/apis-tools/camunda-api-rest/specifications/update-user-task.api.mdx
  • docs/apis-tools/console-sm-api/specifications/console-sm-admin-api.info.mdx
  • docs/apis-tools/console-sm-api/specifications/get-clusters.api.mdx
  • docs/apis-tools/console-sm-api/specifications/get-usage-metrics.api.mdx
  • docs/apis-tools/console-sm-api/specifications/sidebar.ts
  • docs/apis-tools/operate-api/sidebar-schema.js
  • docs/apis-tools/operate-api/specifications/by-id.api.mdx
  • docs/apis-tools/operate-api/specifications/by-key-1.api.mdx
  • docs/apis-tools/operate-api/specifications/by-key-2.api.mdx
  • docs/apis-tools/operate-api/specifications/by-key-3.api.mdx
  • docs/apis-tools/operate-api/specifications/by-key-4.api.mdx
  • docs/apis-tools/operate-api/specifications/by-key-5.api.mdx
  • docs/apis-tools/operate-api/specifications/by-key-6.api.mdx
  • docs/apis-tools/operate-api/specifications/by-key.api.mdx
  • docs/apis-tools/operate-api/specifications/delete.api.mdx
  • docs/apis-tools/operate-api/specifications/get-statistics.api.mdx
  • docs/apis-tools/operate-api/specifications/operate-public-api.info.mdx
  • docs/apis-tools/operate-api/specifications/search-1.api.mdx
  • docs/apis-tools/operate-api/specifications/search-2.api.mdx
  • docs/apis-tools/operate-api/specifications/search-3.api.mdx
  • docs/apis-tools/operate-api/specifications/search-4.api.mdx
  • docs/apis-tools/operate-api/specifications/search-5.api.mdx
  • docs/apis-tools/operate-api/specifications/search-6.api.mdx
  • docs/apis-tools/operate-api/specifications/search-7.api.mdx
  • docs/apis-tools/operate-api/specifications/search.api.mdx
  • docs/apis-tools/operate-api/specifications/sequence-flows-by-key.api.mdx
  • docs/apis-tools/operate-api/specifications/sidebar.js
  • docs/apis-tools/operate-api/specifications/sidebar.ts
  • docs/apis-tools/operate-api/specifications/xml-by-key-1.api.mdx
  • docs/apis-tools/operate-api/specifications/xml-by-key.api.mdx
  • docs/apis-tools/tasklist-api-rest/sidebar-schema.js
  • docs/apis-tools/tasklist-api-rest/specifications/assign-task.api.mdx
  • docs/apis-tools/tasklist-api-rest/specifications/complete-task.api.mdx
  • docs/apis-tools/tasklist-api-rest/specifications/get-form.api.mdx
  • docs/apis-tools/tasklist-api-rest/specifications/get-task-by-id.api.mdx
  • docs/apis-tools/tasklist-api-rest/specifications/get-variable-by-id.api.mdx
  • docs/apis-tools/tasklist-api-rest/specifications/save-draft-task-variables.api.mdx
  • docs/apis-tools/tasklist-api-rest/specifications/search-task-variables.api.mdx
  • docs/apis-tools/tasklist-api-rest/specifications/search-tasks.api.mdx
  • docs/apis-tools/tasklist-api-rest/specifications/sidebar.js
  • docs/apis-tools/tasklist-api-rest/specifications/sidebar.ts
  • docs/apis-tools/tasklist-api-rest/specifications/tasklist-rest-api.info.mdx
  • docs/apis-tools/tasklist-api-rest/specifications/unassign-task.api.mdx
  • docs/apis-tools/zeebe-api-rest/sidebar-schema.js
  • docs/apis-tools/zeebe-api-rest/specifications/assign-a-user-task.api.mdx
  • docs/apis-tools/zeebe-api-rest/specifications/complete-a-user-task.api.mdx
  • docs/apis-tools/zeebe-api-rest/specifications/get-cluster-topology.api.mdx
  • docs/apis-tools/zeebe-api-rest/specifications/sidebar.js
  • docs/apis-tools/zeebe-api-rest/specifications/sidebar.ts
  • docs/apis-tools/zeebe-api-rest/specifications/unassign-a-user-task.api.mdx
  • docs/apis-tools/zeebe-api-rest/specifications/update-a-user-task.api.mdx
  • docs/apis-tools/zeebe-api-rest/specifications/zeebe-rest-api.info.mdx

You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines.

@pepopowitz pepopowitz mentioned this pull request Nov 26, 2024
9 tasks
@akeller
Copy link
Member

akeller commented Dec 2, 2024

Contributes to #4560. Feel free to merge it at your convenience @akeller; I decided I didn't want to just start dumping big commits into your PR, or wreck how you were tracking your progress.

We can either use that PR or close it and start fresh. Given my shift in priorities, it's very unlikely I'll be able to help with this work. My PR did give me something to point to when people asked "why can't we just update to Docusaurus 3?!" As our docs infra DRI, you can close it or continue to work with it, doesn't matter to me @pepopowitz.

@akeller
Copy link
Member

akeller commented Dec 2, 2024

Things this PR doesn't include, but I learned will also be necessary in the d3 conversion:

  • converting the older version specs 😭. We don't generate these; they become basically "hardcoded" when we cut each version. I think this will involve tracking down the exact spec at the time of cutting each version, each API, and hacking the regeneration process to put things in the correct place.
  • Rewrite of the DocItem/Metadata and DocCard components, which use useDoc from the base theme, which is no longer exposed to us.

I'm still digging out of notifications, but do you have this work represented somewhere outside of this PR?

@pepopowitz
Copy link
Collaborator Author

Things this PR doesn't include, but I learned will also be necessary in the d3 conversion:

  • converting the older version specs 😭. We don't generate these; they become basically "hardcoded" when we cut each version. I think this will involve tracking down the exact spec at the time of cutting each version, each API, and hacking the regeneration process to put things in the correct place.
  • Rewrite of the DocItem/Metadata and DocCard components, which use useDoc from the base theme, which is no longer exposed to us.

I'm still digging out of notifications, but do you have this work represented somewhere outside of this PR?

I don't, right now it's in my head as things I wanted to follow up with this week. I will track them if I don't get to them very soon.

@akeller akeller added the deploy Stand up a temporary docs site with this PR label Dec 2, 2024
@akeller
Copy link
Member

akeller commented Dec 2, 2024

@pepopowitz do you expect this PR to build? I added the deploy label just to make sure things looked good, but realized the build failed.

@pepopowitz
Copy link
Collaborator Author

I don't think it will build, at least not yet. Both the things I called out earlier would need to be resolved for this to build (if there aren't also build issues in the base branch).

Don't worry about approving this for now, though. I think the whole d-rex 3 branch needs to be updated on main, and that makes this branch probably meaningless right now.

@pepopowitz pepopowitz merged commit eaaf93f into update-docs Dec 4, 2024
9 of 11 checks passed
@pepopowitz pepopowitz deleted the pepopowitz/update-docs-apis branch December 4, 2024 21:22
Copy link
Contributor

github-actions bot commented Dec 4, 2024

⚠️ Preview environment for commit eaaf93f is being deleted. This usually takes 2-3 minutes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
d3 Path to Docusaurus 3 deploy Stand up a temporary docs site with this PR
Projects
Archived in project
Development

Successfully merging this pull request may close these issues.

2 participants