Closed Bug 1461815 Opened 7 years ago Closed 4 years ago

Include versions in the docs paths for api, event reference

Categories

(Taskcluster :: Services, enhancement)

Product:
Taskcluster
Component:
Services
Type:
enhancement
Priority:
Not set
Severity:
normal

Tracking

(Not tracked)

Status:
RESOLVED INCOMPLETE

People

(Reporter: dustin, Unassigned, Mentored)

References

Details

(Keywords: good-first-bug)

* taskcluster-queue (api: _v1_ | events: _v1_) with those linking to something like /reference/platform/taskcluster-queue/references/v1/api This needs to * Work in both the existing and new site * Include redirects for all existing paths to the new paths
Summary: Include versions in the paths for api, event reference → Include versions in the docs paths for api, event reference
Depends on: 1460019
Assignee: nobody → bugzeeeeee
Blocks: docs

(I'm doing a bit of a spring cleaning of bugs) Is this something you're actually currently working on, Hassan?

Flags: needinfo?(helfi92)

I'm not currently working on this but it will need to be done.

Flags: needinfo?(helfi92)
Component: Documentation → Services
Status: NEW → ASSIGNED

Work in both the existing and new site

Is this still true? (For example we're not working on updating Quick Start in tools)

Flags: needinfo?(dustin)

That was a long time ago. No, not anymore.

Flags: needinfo?(dustin)

Do I understand correctly that this depends on your "Documentation" PR being landed? Seems to be the stuff where these changes should be made :)

Flags: needinfo?(helfi92)

Correct. It depends on https://github.com/taskcluster/taskcluster/pull/216.

Flags: needinfo?(helfi92)
No longer blocks: docs

I am wondering if this can be a good contributor bug?

Flags: needinfo?(dustin)

I bet it would! Let's try to get some attention on it sooner rather than later, since I would like to have this in place before we switch to the new rootUrl for Firefox CI, so we minimize the number of times users much change URLs.

Flags: needinfo?(dustin)
Assignee: bugzeeeeee → nobody
Mentor: bugzeeeeee, dustin
Status: ASSIGNED → NEW
Keywords: good-first-bug
Assignee: nobody → ialokkumarsingh0

You'll need to look both at the source for yarn generate (infrastructure/builder/src/generate, which controls where documentation files appear under ui/docs, and for the ui docs themselves, to figure out how to make this change.

Hopefully this patch will at least give us better debugging.

Are you still working on this?

Flags: needinfo?(ialokkumarsingh0)

No, You can assign someone else.

Flags: needinfo?(ialokkumarsingh0)
Assignee: ialokkumarsingh0 → nobody

Hi, I would like to work on this issue. Could you please assign it to me? Thanks.

Flags: needinfo?(dustin)

Has anyone been assigned this?

Hi Soundharya -- yes, please go ahead.

Assignee: nobody → soundharyabharatiya
Flags: needinfo?(dustin)

Thanks, Dustin.

I understand that the versions have to be added inside the links.
I have some questions in addition to that:

  1. Could you please let me know where I have to look into the codebase for existing and new site?
  2. Could you please give me one instance for API and event reference, where it is happening?

Thanks.

Sure, good questions..

  1. Happily, enough time has passed that we only need to worry about one site (the React code in ui/).
  2. Hooks (api / exchanges) (note: you can ignore logs, as they are not versioned the same way).

Hi Dustin,

Thanks so much for the answer.

I tried making some tweaks in API section by changing the routes param. But, it's not changing any routing link at all.

I tried making changes in all these files: https://imgur.com/QxaQJ2T

Could you please guide me through this thing?

Thanks.

I'm a little confused by your question, since the image doesn't show any changes to routes.

The reference documents are in files like ui/docs/reference/core/hooks/api.mdx. I think the first step would be to rename those files so that they contain the version in the path (so something like ui/docs/reference/core/hooks/v1/api.mdx). Once that's done, you'll need to do bit of work to the code that renders the table of contents so that it correctly renders like

  • Hooks (api: v1 / events: v1 / logs)

Hi Dustin,

Thank you. I have made the changes. But, not sure, whether I can make the changes directly at docs-table-of-contents.json cause when I tried to push the code, it's not showing up in the Files Changed over here: https://github.com/taskcluster/taskcluster/pull/1541.

By the way, it's working fine at my end.
Attaching the screenshots: https://imgur.com/Fi8rzlT

That file is generated by yarn generate, so no -- modifying it directly will not work. The key is to modify the file that creates it, https://github.com/taskcluster/taskcluster/blob/master/infrastructure/tooling/src/generate/generators/docs-tocs.js.

Hi Dustin,

I tried adding my changes in the docs-tocs.js but that too not reflecting, when I am committing it.
These are my screenshot: https://imgur.com/ChOpb7G, https://imgur.com/2J8Bn2b

Can you help me with that?
Thanks.

You'll have to run yarn generate from the root directory as outlined in https://github.com/taskcluster/taskcluster/blob/master/dev-docs/development-process.md#generating-code.

Hi Hassan,

Thanks. Now, I can able to generate the links with v1 version: https://imgur.com/ykFY3gC, https://imgur.com/CQQJK1e.
But, now in the navbar, it renders like Hooks (v1 / logs). When I click on v1 - it's pointing to http://localhost:5080/docs/reference/core/hooks/v1/api.

I think, I have to rethink about the conditions which I have written in docs-tocs.js. Could you please let me know, how should I proceed after this?

Assignee: soundharyabharatiya → nobody

I sincerely doubt we will ever have a v2 API!

Status: NEW → RESOLVED
Closed: 4 years ago
Resolution: --- → INCOMPLETE
You need to log in before you can comment on or make changes to this bug.