DOC: dynamically create a version pull-down using javascript #46652

mattip · 2020-10-21T13:17:01Z

Enhancement to create a version pulldown rather than a link to a static list of versions.html

The version is now passed to sphinx from the environment, so the post-processing to mangle the version is no longer needed
The layout template has been changed
- The javascript scripts are loaded in the header, this should be backported to the upstream pytorch_sphinx_theme repo since now the loading stanza appears twice on the page :(. I needed this to activate the new javascript function as the page loads.
- A new snippet of javascript builds a ul list of versions on document loading (provides consistency across documentation versions)
  - The snippet will try to match the current document to the one from the other versions. If there is a match, switching versions will keep you at the same page.
- The version list is now below the search bar.

I could not get the page existence check to work asynchronously, so page loading time takes a hit. Is the UX improvement worth it? I was basing this off the warning in the NumPy docs when you view older documentation, this is a page with no parallel in the latest version, so the message will pre-populate a search qeury (source code here). maybe I missed something? In any case, the NumPy script only needs to check for the latest page, my adaptaion scans all the versions.

Help here would be welcome from people fluent in web front-end programming.

mattip · 2020-10-21T13:34:32Z

docs/source/_static/docversions.js

+                open_list = '<li id="current">'
+            }
+        }
+        const pathPattern = /docs\/(build\/html|stable|master|[0-9.rc]+)(.*)/;


whether you build locally or deploy to pytorch/pytorch.github.io, the document URL will look like

file:///home/user/pytorch/docs/build/html/generated/torch.nn.parameter.Parameter.html or https://pytorch.org/docs/1.6.0/generated/torch.nn.parameter.Parameter.html

So the docs part is a consistent anchor, then either build/html or one of the versions (stable', master, 1.6.0` etc), then the actual document name we are interested in.

mattip · 2020-10-21T13:36:44Z

docs/source/_static/docversions.js

+        document.write(open_list);
+        document.write('<a id=ID href="URL">VERSION</a> </li>\n'
+                        .replace('VERSION', label)
+                        .replace('URL', url));


I couldn't get this to work with async: true and then rewriting the item.href.

mattip · 2020-10-21T13:39:25Z

docs/source/_templates-stable/layout.html

+       <script type="text/javascript" data-url_root="{{ pathto('', 1) }}" src="{{ pathto('_static/docversions.js', 1) }}"></script>
+{{ super() }}
+{% endblock %}
+


This si the bit that should be upstreamed to the theme (without the _static/docversions.js). Is there a reason they have it so late in the template there? Connected to {% if not embedded %} ?

mattip · 2020-10-21T13:41:25Z

docs/source/_templates-stable/layout.html

+              {% endif %}
+            {% endif %}
+{% endblock %}
+


This block overrides the original sidebartitle block

dr-ci · 2020-10-22T07:05:25Z

🔗 Helpful links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/46652
🔧 Opt-in to CIFlow to control what jobs run on your PRs

💊 CI failures summary and remediations

As of commit 766bafb (more details on the Dr. CI page):

Commit 766bafb was recently pushed. Waiting for builds...

This comment was automatically generated by Dr. CI (expand for details).

Follow this link to opt-out of these comments for your Pull Requests.

Please report bugs/suggestions to the (internal) Dr. CI Users group.

Click here to manually regenerate this comment.

mattip · 2020-10-22T07:52:50Z

Now the linking is working properly. This page is available in all versions, this page is only available in versions 1.6.0 and higher.

facebook-github-bot · 2020-10-30T17:31:42Z

Hi @mattip!

Thank you for your pull request. We require contributors to sign our Contributor License Agreement, and yours needs attention.

You currently have a record in our system, but we do not have a signature on file.

In order for us to review and merge your code, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

If you have received this in error or have any questions, please contact us at cla@fb.com. Thanks!

brianjo

I looked at the preview for this and I think it's good. Would love to see this added to release going forward, and master. (We don't need to rebuild previous versions.)

seemethere

looks mostly good, just one minor nit

docs/source/_static/docversions.js

Co-authored-by: Eli Uriegas <1700823+seemethere@users.noreply.github.com>

brianjo · 2020-11-11T21:51:29Z

Converted to Draft, @ranman is going to work on some changes.

facebook-github-bot · 2021-09-22T04:54:01Z

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks!

pytorchbot · 2022-04-12T03:20:35Z

Looks like this PR hasn't been updated in a while so we're going to go ahead and mark this as Stale.
Feel free to remove the Stale label if you feel this was a mistake.
If you are unable to remove the Stale label please contact a maintainer in order to do so.
Stale pull requests will automatically be closed 30 days after being marked Stale

mattip · 2022-04-12T15:54:48Z

This was mostly a proof-of-concept. Closing. At some point, the pytorch doc team may want to look at how the pydata theme implemented a version pulldown.

DOC: dynamically create a version pull-down using javascript

c18d604

pytorchbot added the open source label Oct 21, 2020

mattip commented Oct 21, 2020

View reviewed changes

zou3519 requested review from jlin27 and brianjo October 21, 2020 14:15

zou3519 added the triaged This issue has been looked at a team member, and triaged and prioritized into an appropriate module label Oct 21, 2020

zou3519 self-requested a review October 21, 2020 14:16

DOC: fix regex for CI, document javascript

41a547e

facebook-github-bot added the cla signed label Oct 31, 2020

brianjo requested a review from seemethere November 11, 2020 16:41

brianjo approved these changes Nov 11, 2020

View reviewed changes

seemethere approved these changes Nov 11, 2020

View reviewed changes

docs/source/_static/docversions.js Outdated Show resolved Hide resolved

Update docs/source/_static/docversions.js

766bafb

Co-authored-by: Eli Uriegas <1700823+seemethere@users.noreply.github.com>

brianjo marked this pull request as draft November 11, 2020 21:50

brianjo requested a review from ranman November 11, 2020 21:53

mattip mentioned this pull request Jan 11, 2021

DOC: dynamically create a version pull-down using javascript pytorch/audio#1175

Closed

pytorchbot added the Stale label Apr 12, 2022

mattip closed this Apr 12, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: dynamically create a version pull-down using javascript #46652

DOC: dynamically create a version pull-down using javascript #46652

mattip commented Oct 21, 2020

mattip Oct 21, 2020

mattip Oct 21, 2020

mattip Oct 21, 2020

mattip Oct 21, 2020

dr-ci bot commented Oct 22, 2020 •

edited by facebook-github-bot

Loading

mattip commented Oct 22, 2020

facebook-github-bot commented Oct 30, 2020

brianjo left a comment

seemethere left a comment

brianjo commented Nov 11, 2020

facebook-github-bot commented Sep 22, 2021

pytorchbot commented Apr 12, 2022

mattip commented Apr 12, 2022

DOC: dynamically create a version pull-down using javascript #46652

DOC: dynamically create a version pull-down using javascript #46652

Conversation

mattip commented Oct 21, 2020

mattip Oct 21, 2020

Choose a reason for hiding this comment

mattip Oct 21, 2020

Choose a reason for hiding this comment

mattip Oct 21, 2020

Choose a reason for hiding this comment

mattip Oct 21, 2020

Choose a reason for hiding this comment

dr-ci bot commented Oct 22, 2020 • edited by facebook-github-bot Loading

🔗 Helpful links

💊 CI failures summary and remediations

mattip commented Oct 22, 2020

facebook-github-bot commented Oct 30, 2020

brianjo left a comment

Choose a reason for hiding this comment

seemethere left a comment

Choose a reason for hiding this comment

brianjo commented Nov 11, 2020

facebook-github-bot commented Sep 22, 2021

pytorchbot commented Apr 12, 2022

mattip commented Apr 12, 2022

dr-ci bot commented Oct 22, 2020 •

edited by facebook-github-bot

Loading