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.

Sign up for GitHub

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

Jump to bottom

API documentation for < 7.0 links broken #44042

Closed
mobilutz opened this issue Jan 1, 2022 · 10 comments · Fixed by #44086
Closed

API documentation for < 7.0 links broken #44042

mobilutz opened this issue Jan 1, 2022 · 10 comments · Fixed by #44086

Comments

@mobilutz
Copy link

mobilutz commented Jan 1, 2022

I copied this over from the rails discussion board to here:
https://discuss.rubyonrails.org/t/api-documentation-broken-for-7-0-0-versions/79574

Steps to reproduce

Expected behavior

Correct documentation page being displayed:
https://api.rubyonrails.org/v6.1.4/classes/AbstractController.html

Actual behavior

Redirect to the wrong URL which is also a 404 page:
https://edgeapi.rubyonrails.org/undefinedclasses/AbstractController.html

System configuration

Rails version: N/A

Ruby version: N/A
@fxn
Copy link
Member

fxn commented Jan 2, 2022 •
edited
Loading

I believe we have two issues with 6.1 docs:

  1. Some were not properly generated due to missing system dependencies or Bundler conflicts.
  2. In the one I have been able to generate manually as a quick fix, the links in the sidebar do not preserve the prefix. For instance, if you go to https://api.rubyonrails.org/v6.1/ and click on anything in the sidebar, you'll see the main panel is showing 7.0 docs, that is what you'd get without the path prefix.

I believe we should fix (2) first, and then regenerate 6.1 and 7.0 documentation.

@p8 (2) seems to be happening to all 6.1.x docs and it went unnoticed because they were not using the path prefixes like /v6.1. This was made apparent with Rails 7. Could it be related to the SDoc upgrade that replaced frames?

/cc @zzak

@fxn
Copy link
Member

fxn commented Jan 2, 2022

As a quick fix, we could also manually downgrade SDoc for all 6.1 and regenerate with frames, since people do not have documentation.

@p8 @zzak I'll leave that to your preference.

@p8
Copy link
Member

p8 commented Jan 2, 2022

Thanks @fxn !
I’ll have a look tomorrow.

p8 added a commit to p8/sdoc that referenced this issue Jan 4, 2022
@p8
Make sidepanel work better with relative paths/URLs
58fc40a 
Turbolinks does not consider relative URLs to assets identical even if the
absolute URL would be the same.
When visiting /index.html and it has the following css included:

    <link rel="stylesheet" href="css/panel.css" type="text/css" data-turbolinks-track="reload" />

... the panel.css would not be seen as identical as when visiting
/classes/Array.html with the following css included:

    <link rel="stylesheet" href="css/panel.css" type="text/css" data-turbolinks-track="reload" />

This results in page reloads and losing the context of the panel when
using search. This was previously fixed by making all URLs to assets
absolute. But absolute URLs fail when we have multiple versions of the
docs in subdirectories like: https://api.rubyonrails.org/v6.1/
See: rails/rails#44042

By removing the `data-turbolinks-track` attribute we can use relative
URLs again. This does mean the assets get reloaded everytime we navigate
to another page, which required a change to search results.

The search results are persisted across navigations using the
data-turbolinks-permanent attribute. When we no longer track the assets,
the search tree gets rebuild for every navigation. But the URLs to the
search results are no longer available in the panel DOM as these are
stored in jQuery data attributes.
jQuery does not persist this data when navigating to another page:

    The data- attributes are pulled in the first time the data property
    is accessed and then are no longer accessed or mutated (all data
    values are then stored internally in jQuery).

    https://api.jquery.com/data/#data1

By storing the path in a HTML data-attribute it starts working again.
@p8 p8 mentioned this issue Jan 4, 2022
Merged
p8 added a commit to p8/sdoc that referenced this issue Jan 4, 2022
@p8
Make sidepanel work better with relative paths/URLs
7cd2aa3 
Turbolinks does not consider relative URLs to assets identical even if the
absolute URL would be the same.
For example when visiting /index.html and it has the following css link:

    <link rel="stylesheet" href="css/panel.css" type="text/css" data-turbolinks-track="reload" />

... the panel.css would not be seen as identical as when visiting
/classes/Array.html with the following css link:

    <link rel="stylesheet" href="../css/panel.css" type="text/css" data-turbolinks-track="reload" />

This results in page reloads and losing the context of the panel when
using search. This was previously fixed by making all URLs to assets
absolute. But absolute URLs fail when we have multiple versions of the
docs in subdirectories like: https://api.rubyonrails.org/v6.1/
See: rails/rails#44042

Removing the data-turbolinks-track attribute
--------------------------------------------

By removing the `data-turbolinks-track` attribute we can use relative
URLs again. This does mean the assets get reloaded everytime we navigate
to another page, which required a change to search results.

Fixing the search results URLs
------------------------------

The search results are persisted across navigations using the
data-turbolinks-permanent attribute. When we no longer track the assets,
the search tree gets rebuild for every navigation. But the URLs to the
search results are no longer available in the panel DOM as these are
stored in jQuery data attributes.
jQuery does not persist this data when navigating to another page:

    The data- attributes are pulled in the first time the data property
    is accessed and then are no longer accessed or mutated (all data
    values are then stored internally in jQuery).

    https://api.jquery.com/data/#data1

By storing the path in a HTML data-attribute it starts working again.

Updating the rel_prefix
-----------------------

When we use relative URLs the rel_prefix will change when we navigate to
page that is on another level. For example navigating from
`/classes/ActiveRecord.html` to `/classes/ActiveRecord/Attributes/ClassMethods.html`
changes the prefix from `../` to `../../../`.
If the prefix can change on every navigation, the prefix needs to be
loaded from the meta tag everytime.
@zzak
Copy link
Member

zzak commented Jan 5, 2022

Thanks @p8 for looking into this 🙇

@p8
Copy link
Member

p8 commented Jan 5, 2022 •
edited
Loading

Thanks @zzak! https://github.com/zzak/sdoc/pull/176 should fix this.

p8 added a commit to p8/sdoc that referenced this issue Jan 5, 2022
@p8
Make sidepanel work with relative paths/URLs
09f80bd 
With the migration to a frameless layout, the URLs to assets were made
absolute instead of relative because of Turbolinks asset tracking.
But absolute URLs fail when we have multiple versions of the docs in
subdirectories like: https://api.rubyonrails.org/v6.1/
See: rails/rails#44042

Turbolinks tracking requires absolute URLs
-------------------------------------------

Turbolinks does not consider relative URLs to assets identical when
tracking assets for reload, even if the absolute URL would be the same.
For example when visiting /index.html, in the following css link:

    <link rel="stylesheet" href="css/panel.css" type="text/css" data-turbolinks-track="reload" />

... the panel.css would not be seen as identical as when visiting
/classes/Array.html with the following css link:

    <link rel="stylesheet" href="../css/panel.css" type="text/css" data-turbolinks-track="reload" />

This results in page reloads as Turbolinks wants to make sure it has all
the latests assets loaded. With a page reload we lose the context of the
panel when using search.

Instead of using absolute URLs another solution would be to remove the
`data-turbolinks-track` attribute.

Removing the data-turbolinks-track attribute
---------------------------------------------

By removing the `data-turbolinks-track` attribute we can use relative
URLs again. In this case Turbolinks just reloads the assets everytime
we navigate to another page. Reloading assets has a small performance
cost, but this seems barely noticable. It also requires a change to search results.

Fixing the search results URLs
------------------------------

The search results are persisted across navigations using the
`data-turbolinks-permanent` attribute. When we no longer track the assets,
the search tree gets rebuild for every navigation. But the URLs to the
search results are no longer available in the panel DOM as these are
stored in jQuery data attributes.
jQuery does not persist this data when navigating to another page:

    The data- attributes are pulled in the first time the data property
    is accessed and then are no longer accessed or mutated (all data
    values are then stored internally in jQuery).

    https://api.jquery.com/data/#data1

By storing the path in a HTML data-attribute it starts working again.

Updating the rel_prefix
-----------------------

When we use relative URLs the rel_prefix will change when we navigate to
a page that is on another level. For example, navigating from
`/classes/ActiveRecord.html` to `/classes/ActiveRecord/Attributes/ClassMethods.html`
changes the prefix from `../` to `../../../`.
If the prefix can change on every navigation, the prefix needs to be
loaded from the meta tag everytime, instead of on the first
initialization only.
p8 added a commit to p8/sdoc that referenced this issue Jan 5, 2022
@p8
Make sidepanel work with relative paths/URLs
da08c8c 
With the migration to a frameless layout, the URLs to assets were made
absolute instead of relative because of Turbolinks asset tracking.
But absolute URLs fail when we have multiple versions of the docs in
subdirectories like: https://api.rubyonrails.org/v6.1/
See: rails/rails#44042

Turbolinks tracking requires absolute URLs
-------------------------------------------

Turbolinks does not consider relative URLs to assets identical when
tracking assets for reload, even if the absolute URL would be the same.
For example when visiting /index.html, in the following css link:

    <link rel="stylesheet" href="css/panel.css" type="text/css" data-turbolinks-track="reload" />

... the panel.css would not be seen as identical as when visiting
/classes/Array.html with the following css link:

    <link rel="stylesheet" href="../css/panel.css" type="text/css" data-turbolinks-track="reload" />

This results in page reloads as Turbolinks wants to make sure it has all
the latests assets loaded. With a page reload we lose the context of the
panel when using search.

Instead of using absolute URLs another solution would be to remove the
`data-turbolinks-track` attribute.

Removing the data-turbolinks-track attribute
---------------------------------------------

By removing the `data-turbolinks-track` attribute we can use relative
URLs again. In this case Turbolinks just reloads the assets everytime
we navigate to another page. Reloading assets has a small performance
cost, but this seems barely noticable. It also requires a change to search results.

Fixing the search results URLs
------------------------------

The search results are persisted across navigations using the
`data-turbolinks-permanent` attribute. When we no longer track the assets,
the search tree gets rebuild for every navigation. But the URLs to the
search results are no longer available in the panel DOM as these are
stored in jQuery data attributes.
jQuery does not persist this data when navigating to another page:

    The data- attributes are pulled in the first time the data property
    is accessed and then are no longer accessed or mutated (all data
    values are then stored internally in jQuery).

    https://api.jquery.com/data/#data1

By storing the path in a HTML data-attribute it starts working again.

Updating the rel_prefix
-----------------------

When we use relative URLs the rel_prefix will change when we navigate to
a page that is on another level. For example, navigating from
`/classes/ActiveRecord.html` to `/classes/ActiveRecord/Attributes/ClassMethods.html`
changes the prefix from `../` to `../../../`.
If the prefix can change on every navigation, the prefix needs to be
loaded from the meta tag everytime, instead of on the first
initialization only.
p8 added a commit to p8/sdoc that referenced this issue Jan 5, 2022
@p8
Make sidepanel work with relative paths/URLs
60c66fd 
With the migration to a frameless layout, the URLs to assets were made
absolute instead of relative because of Turbolinks asset tracking.
But absolute URLs fail when we have multiple versions of the docs in
subdirectories like: https://api.rubyonrails.org/v6.1/
See: rails/rails#44042

Turbolinks tracking requires absolute URLs
-------------------------------------------

Turbolinks does not consider relative URLs to assets identical when
tracking assets for reload, even if the absolute URL would be the same.
For example when visiting /index.html, in the following css link:

    <link rel="stylesheet" href="css/panel.css" type="text/css" data-turbolinks-track="reload" />

... the panel.css would not be seen as identical as when visiting
/classes/Array.html with the following css link:

    <link rel="stylesheet" href="../css/panel.css" type="text/css" data-turbolinks-track="reload" />

This results in page reloads as Turbolinks wants to make sure it has all
the latests assets loaded. With a page reload we lose the context of the
panel when using search.

Instead of using absolute URLs another solution would be to remove the
`data-turbolinks-track` attribute.

Removing the data-turbolinks-track attribute
---------------------------------------------

By removing the `data-turbolinks-track` attribute we can use relative
URLs again. In this case Turbolinks just reloads the assets everytime
we navigate to another page. Reloading assets has a small performance
cost, but this seems barely noticable. It also requires a change to search results.

Fixing the search results URLs
------------------------------

The search results are persisted across navigations using the
`data-turbolinks-permanent` attribute. When we no longer track the assets,
the search tree gets rebuild for every navigation. But the URLs to the
search results are no longer available in the panel DOM as these are
stored in jQuery data attributes.
jQuery does not persist this data when navigating to another page:

    The data- attributes are pulled in the first time the data property
    is accessed and then are no longer accessed or mutated (all data
    values are then stored internally in jQuery).

    https://api.jquery.com/data/#data1

By storing the path in a HTML data-attribute it starts working again.

Updating the rel_prefix
-----------------------

When we use relative URLs the rel_prefix will change when we navigate to
a page that is on another level. For example, navigating from
`/classes/ActiveRecord.html` to `/classes/ActiveRecord/Attributes/ClassMethods.html`
changes the prefix from `../` to `../../../`.
If the prefix can change on every navigation, the prefix needs to be
loaded from the meta tag everytime, instead of on the first
initialization only.
@rafaelfranca rafaelfranca mentioned this issue Jan 5, 2022
Closed
p8 added a commit to p8/sdoc that referenced this issue Jan 5, 2022
@p8
Make sidepanel work with relative paths/URLs
a9a1cd5 
With the migration to a frameless layout, the URLs to assets were made
absolute instead of relative because of Turbolinks asset tracking.
But absolute URLs fail when we have multiple versions of the docs in
subdirectories like: https://api.rubyonrails.org/v6.1/
See: rails/rails#44042

Turbolinks tracking requires absolute URLs
-------------------------------------------

Turbolinks does not consider relative URLs to assets identical when
tracking assets for reload, even if the absolute URL would be the same.
For example when visiting /index.html, in the following css link:

    <link rel="stylesheet" href="css/panel.css" type="text/css" data-turbolinks-track="reload" />

... the panel.css would not be seen as identical as when visiting
/classes/Array.html with the following css link:

    <link rel="stylesheet" href="../css/panel.css" type="text/css" data-turbolinks-track="reload" />

This results in page reloads as Turbolinks wants to make sure it has all
the latests assets loaded. With a page reload we lose the context of the
panel when using search.

Instead of using absolute URLs another solution would be to remove the
`data-turbolinks-track` attribute.

Removing the data-turbolinks-track attribute
---------------------------------------------

By removing the `data-turbolinks-track` attribute we can use relative
URLs again. In this case Turbolinks just reloads the assets everytime
we navigate to another page. Reloading assets has a small performance
cost, but this seems barely noticable. It also requires a change to search results.

Fixing the search results URLs
------------------------------

The search results are persisted across navigations using the
`data-turbolinks-permanent` attribute. When we no longer track the assets,
the search tree gets rebuild for every navigation. But the URLs to the
search results are no longer available in the panel DOM as these are
stored in jQuery data attributes.
jQuery does not persist this data when navigating to another page:

    The data- attributes are pulled in the first time the data property
    is accessed and then are no longer accessed or mutated (all data
    values are then stored internally in jQuery).

    https://api.jquery.com/data/#data1

By storing the path in a HTML data-attribute it starts working again.

Updating the rel_prefix
-----------------------

When we use relative URLs the rel_prefix will change when we navigate to
a page that is on another level. For example, navigating from
`/classes/ActiveRecord.html` to `/classes/ActiveRecord/Attributes/ClassMethods.html`
changes the prefix from `../` to `../../../`.
If the prefix can change on every navigation, the prefix needs to be
loaded from the meta tag everytime, instead of on the first
initialization only.
@p8 p8 mentioned this issue Jan 5, 2022
Merged
p8 added a commit to p8/rails that referenced this issue Jan 5, 2022
@p8
Update sdoc to 2.3.0
199b660 
With the migration of SDoc to a frameless layout, the URLs to assets
were made absolute instead of relative because of Turbolinks asset
tracking.  But absolute URLs fail when we have multiple versions of the
docs in subdirectories like: https://api.rubyonrails.org/v6.1/

This version of sdoc restores relative URLs by disabling the Turbolinks
asset tracking.

Fixes rails#44042
@fxn
Copy link
Member

fxn commented Jan 5, 2022 •
edited
Loading

I have regenerated the APIs for all v6.1.[0-4], and the one linked to v6.1 (v6.1.4.4).

@rafaelfranca
Copy link
Member

Thanks!

@fxn
Copy link
Member

fxn commented Jan 5, 2022

And now all v6.1.x.y.

@dmke
Copy link

dmke commented Jan 6, 2022

This issue solves only half of #43955. As written there, this still won't work:

  1. Visit https://api.rubyonrails.org/v6.1/
  2. In the main content area, click on the "Active Record" link in the second section:

image

  1. I'm redirected to https://edgeapi.rubyonrails.org/activerecord/README_rdoc.html, which answers with a 404 error.

The generated link seems to be wrong, and should be pointing to ./files/activerecord/README_rdoc.html, not ../activerecord/README_rdoc.html:

image

N.B.: On https://api.rubyonrails.org, the same link points to ../../files/activerecord/README_rdoc.html, so there's still something wrong with generating relative URLs.

@p8
Copy link
Member

p8 commented Jan 6, 2022

Thanks @fxn!
@dmke I'll have a look if I can fix those links.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Update sdoc to 2.3.0 p8/rails
6 participants
@fxn @p8 @rafaelfranca @zzak @dmke @mobilutz