Clicking in the Blosc logo should redirect to the home page

[FrancescAlted]

Right now, if we are in say, https://www.blosc.org/python-blosc2/release_notes/index.html, and click to the blosc logo in upper left, this redirects you to: https://www.blosc.org/python-blosc2/index.html. I think redirecting to https://www.blosc.org is much better in terms of navegation. And the same applies to the C-Blosc2 and Python-Blosc doc pages.

@datapythonista what do you think?

[datapythonista]

I agree. This doesn't need to be implemented here bit in the other repos. Besides the logo going to the global home, I think the navigation bar should have the same menu options and the same look. I'll have a look.

[FrancescAlted]

I see that the top navigation bar in sub-projects (C-Blosc2, Python-Blosc, Python-Blosc2) is not showing up anymore. Also clicking in the Blosc logo redirects you to a non existing place. I think this is still work in progress, but FYI.

[datapythonista]

Yes, I realized on Friday, I'll fix it today. I couldn't test the logo link well until everything was put together. It's a bug in the sphinx theme, but I can implement a workaround. For the navigation, I'm checking what's best. Sphinx is limiting the options, but I think I can do something that should make navigation nice and intuitive. Will ping you a bit later with the PRs.

[datapythonista]

I opened 3 PRS, one for each project, fixing the logo link, and the navigation (which will show in the sidebar, the top bar will have the same links as the website/blog):

• Fix navigation c-blosc2#417
• Fix navigation python-blosc#287
• Fix navigation python-blosc2#53

This is what makes more sense to me, but after you test it, let me know if anything doesn't make sense to you.

[FrancescAlted]

Thanks. @martaiborra could you do a review on this, and if if looks good to you, please merge the different PRs.

[FrancescAlted]

That is taking a really good shape. One minor thing: when clicking on the github button of the navigation bar, one is always redirected to https://github.com/Blosc/c-blosc2, irregardingly of the project that one is browsing. If it is not possible to send to the different projects, maybe it is better to redirect to https://github.com/Blosc. Thanks.

[datapythonista]

My bad. They can be different, I just copy-pasted the settings and forgot to update it. I just opened PRs to fix them.

[FrancescAlted]

Ok. After that, I think the only pending task is to update links to the new documentation site and remove the readthedocs projects. Correct?

[datapythonista]

I already updated updated the links to the docs in the READMEs, those are the only ones I'm aware of. If there are more links to the old docs, yes, that'd be pending. Copying an updated version of this comment with the things that I'm aware of:

• Set up redirects in readthedocs to point to the new version. Never used readthedocs, and I don't have access to the admin, but there is info here, seems easy: https://docs.readthedocs.io/en/stable/user-defined-redirects.html
• Set up redirects in http://python-blosc.blosc.org/ and any other subdomain
• Set up actions in the 3 projects built here that run on tags pushed and trigger this build. Should be something like:

on:
  push:
    tags:
      - '*'

jobs:
  trigger_website_build:
  steps:
  - run: curl -X POST -H "Accept: application/vnd.github.v3+json" -H "Authorization: token $TOKEN" --data '{"event_type": "update_website"}' https://api.github.com/repos/Blosc/blogsite/dispatches
    env:
      TOKEN: ${{ secrets.trigger_website_build_token }}

The secret trigger_website_build_token needs to be generated like this: https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token and stored in settings > secrets

[FrancescAlted]

Thanks for the reminder.

I am not sure we want to activate actions for trigger the docs rendering in the 3 projects. Right now, I'd prefer to deploy the docs manually during the releasing process (see e.g.: Blosc/python-blosc2@7e2403f#diff-e71b27ab83b907d230fca9db0a00150a9c686a2bb8465646d5b5a007de7946fbR55-L58). This introduces less 'magic' and IMO is less error prone in the long run.

Will take care of the other 2 points though.

[datapythonista]

Sounds good. If useful, we can add workflow_dispatch to the CI here, so you can build the docs via the GitHub UI or API.

One thing we discussed but still need to be addressed... This is now set up to build the docs of the main/master branch of each repo. We can easily add to the CI a checkout of the latest tag (in chronological order) with git checkout $(git describe --tags $(git rev-list --tags --max-count=1)). But if we do it now (before the 3 projects are released), the docs will revert to the old format. Not sure how often you release and how different are the docs/API from one version to the next to have an opinion on what makes more sense here.

[FrancescAlted]

Ok. So I tried to use redirections using the instructions at: https://docs.readthedocs.io/en/stable/user-defined-redirects.html. After a lot of attempts, I was really unable to make them working properly. After having a look at readthedocs/readthedocs.org#8143 (the NumPy folks also tried to do the same recently), they also found quite a lot of issues (reading the ticket is quite instructive actually), I decided to entirely remove the projects (C-Blosc2, Python-Blosc and Python-Blosc2) from readthedocs. I just hope I did not fucked too many things in doing this.

[FrancescAlted]

BTW, I noticed that the URLs for the new projects are like: https://www.blosc.org/python-blosc2/python-blosc2.html. Would it possible to reduce them to just https://www.blosc.org/python-blosc2 (and the same for others)? That would be much shorter for docs and the like.

[datapythonista]

BTW, I noticed that the URLs for the new projects are like: https://www.blosc.org/python-blosc2/python-blosc2.html. Would it possible to reduce them to just https://www.blosc.org/python-blosc2 (and the same for others)? That would be much shorter for docs and the like.

The problem comes from how the Sphinx template builds the header. What it does is check the table of contents in the root page, and adds the items there. Then you can append any other link you want to the navigation. What I did is to add just an element to the root page, that points to a second page with the README and the table of contents to the actual sections.

A quick fix for the links it to rename the Sphinx root to something different than the default index.html, and make the page with the README be index.html, so that page would be just /c-blosc2/... But there are still few other minor problems with the approach currently implemented. In the footer there are Previous / Next links that make that "fake" root visible. And the order of the navigation changes depending in which docs the user is at (the current docs must be always the first with this approach).

Something that can make more sense is to leave Sphinx with the default behavior, but try to change the template it uses, so we add the website navigation on top of the Sphinx navigation. There would be two navigation bars then, one on top of the other, something like:

<logo>           Blosc in depth    C-Blosc2     Python-Blosc     Python-Blosc2
                              API reference     Format     Development

I think this would be a much cleaner solution. I don't think it's so complicated, but it can probably take couple of days of work. And I don't have the time right now for it.

For fixing only the links for now, it should be as easy as changing in the Sphinx conf.py of every project the root_doc to for example root:

root_doc = "root"

Then rename index.rst -> root.rst and c-blosc2.rst -> index.rst in the 3 projects, and then update all the links in the configurations of each Sphinx projects external_links and in the Nikola website.

[datapythonista]

For the redirects, there is an option I wouldn't personally implement, that is using JavaScript redirects. That would mean embedding some html in each Sphinx page with a javascript redirect to the new page. For users arriving to the website, the old page would render, and once fully loaded the page would redirect to the new location. The problem of doing it with JavaScript and not with the proper HTTP headers is that search engines would not update the index, as they are not aware of JavaScript redirects (afaik).

It's unfortunate that readthedocs redirects don't work (I never used readthedocs myself), but I think what you did is the best. For some days the links in search engines and users benchmarks will be broken, but after these few annoying days everything will be in place, with pages properly indexed, probably better than before, as all the Blosc pages now live under the same domain, and search engines should give it more important for the relevant keywords.