[DOCS] Make Download Section Easier To Find

[franzihei]

Problem

People are not aware that there is the option to download the Solidity docs and we've had several requests about this recently. The download option is so hidden in the flyout menu (some need to scroll to see it), since the list of versions has grown quite long.

Example:

Solution

Place the download options at a more obvious / easier visible place in the menu.

Related Discussion

https://forum.soliditylang.org/t/please-can-i-get-the-documentation-in-downloadable-form/615/7

[Shorpee]

Would moving the downloads tab to the top be a good solution or is there something else you have in mind for this?

[franzihei]

Moving them above the versions is a good idea in my opinion. I didn't have anything specific in mind for it yet and I think that's a good and easy solution for now!

[chriseth]

I'm actually not sure if we have full control about the layout of this "popup". We could start by mentioning the download options on the first pages of the documentation, maybe close to the "translations" section.

[cameel]

Fortunately we do. The order is defined by our template so we can just swap these two items to get downloads on top.

[cameel]

In that template we can even easily put a link above the fold so that it's always visible.

A link in the footer is also a possibility.

[nishant-sachdeva]

@franzihei @cameel @chriseth Is it fine to move the download section ahead of the versions section?

If needed, we can also add it to the Resources Section.

If that is fine, then I am ready to send in a PR to that effect

[franzihei]

Yes sounds great please do.

Additionally to moving the download section over the versions section in the flyout menu, could you add a green "hint" section on the index page, between Ideas for improving Solidity or this documentation are always welcome, read our contributors guide for more details. and Getting Started which says something like:

Hint:
You can download this documentation as PDF, HTML or Epub by clicking on the versions flyout menu in the left bottom corner and selecting the preferred download format.

[cameel]

#12277 has just been deployed to RTD (https://docs.soliditylang.org/en/latest/) but looks like it didn't work correctly.

The RTD logo is gone but there's no PDF link in its place:

Downloads and versions are also still in the old order when you open the popup.

When reviewing I only checked the rendered version from CircleCI and noticed that the link was missing there but in that version the JS that opens the menu does not load so I thought it was just an artifact of that. Apparently not :)

@nishant-sachdeva Have you tried rendering the docs locally? Or did it work locally and it's only broken at RTD?

[nishant-sachdeva]

Yes, I assumed that javaScript issue was at work as well.

But the download section was above the version section in my local rendering.

Will investigate this Asap

[cameel]

But the download section was above the version section in my local rendering.

Yeah, this is weird. In the PR it's clearly above but not on RTD and this is unlikely to be caused by JS, it's just static HTML. I initially thought that maybe https://docs.soliditylang.org/en/latest/ just has not been updated yet but it usually updates shortly after a merge and the RTD logo is definitely missing (you can still see it on https://docs.soliditylang.org/en/v0.8.10/ which is an older version).

[cameel]

I think I figured out what's happening. This thing is a real mess. So apparently the template can be found in four different places:

• layout.html in Sphinx RTD theme - used only for local rendering.
• versions.html in Sphinx RTD theme - used on ReadTheDocs.
• Our versions.html - overrides the RTD theme.
• footer.html from readthedocs.org - served from an API endpoint at ReadTheDocs, overrides our override.

So ReadTheDocs has an API endpoint that renders the list of versions using their own template. I see a request to this endpoint in dev console and the <!-- Inserted RTD Footer --> comment is in there.

One way to deal with that would be if readthedocs.org allows customizing or disabling the template via their online config (@chriseth would have to check that).

Another would be to customize it on the fly using JS. I don't think it's worth the hassle though and also it would require manipulating the rendered HTML. They are actually planning a redesign to allow custom rendering of the menu from JSON data (readthedocs/readthedocs.org#8052) to make this easier but it's hard to tell when that will land.

I'd suggest to revert the change and look for a different way to make downloads more prominent.

[franzihei]

One way to deal with that would be if readthedocs.org allows customizing or disabling the template via their online config (@chriseth would have to check that).

I just checked in the admin settings and couldn't find anything like that. :(

Generally wondering though: We did adjust the footer / navigation bar since we added the dark mode toggle. How is that possible but the other change not?

[cameel]

Oh, I didn't realize you had access to that too. Great!

Generally wondering though: We did adjust the footer / navigation bar since we added the dark mode toggle. How is that possible but the other change not?

Good question. I wanted to answer that they just chose not to overwrite it but I checked the requests and apparently they do! The thing is that the page has two footers :) The one that readthedocs.org overwrites is hidden at the bottom of the version menu:

The one we modify comes from the theme and the JS does not touch it.

[cameel]

@nishant-sachdeva

Was wondering, shouldn't this be closed now ? We did work on it and add a note about the download section.

And we also talked about how we can't change the base template because it's loaded from some other place.
So, I suppose the issue can be closed ?

Well, I think we can close this given that further improvements will likely require considerable effort that's disproportionate to potential gains.

To summarize, so far we managed to achieve this so far:

• Download section was moved above versions in the flyout menu.
• We added a note about the PDF on the index page.

Unfortunately I see that the downloads section in the flyout menu is currently broken for 0.8.9+. I.e. it's empty and showing no links. I'm not sure if this is related to this enhancement and it's also really hard to verify since it happens only with release versions (latest is fine for example). I'm going to report it as a separate issue.