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.

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

Clicking in the Blosc logo should redirect to the home page #4

Open
FrancescAlted opened this issue Sep 2, 2022 · 18 comments
Open

Comments

@FrancescAlted
Copy link
Member

FrancescAlted commented Sep 2, 2022

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
Copy link
Collaborator

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
Copy link
Member Author

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
Copy link
Collaborator

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
Copy link
Collaborator

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):

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
Copy link
Member Author

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

@FrancescAlted
Copy link
Member Author

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
Copy link
Collaborator

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
Copy link
Member Author

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
Copy link
Collaborator

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:

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
Copy link
Member Author

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
Copy link
Collaborator

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
Copy link
Member Author

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
Copy link
Member Author

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
Copy link
Collaborator

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
Copy link
Collaborator

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.

@FrancescAlted
Copy link
Member Author

FrancescAlted commented Sep 9, 2022

I have been trying to look how to do the redirection for python-blosc.blosc.org in our nginx, but this is taking more time than I'd like to use here. For the time being, I have just disabled the python-blosc.blosc.org entirely. I think @datapythonista is right and that after some initial days where people is looking for docs, they will google for the new site. Damn, this latest redirection part went a bit crazy, but hey, the result is very good already.

@datapythonista
Copy link
Collaborator

If python-blosc is hosted in your own nginx, I think the redirect should work by simply adding this to the server block for the domain:

rewrite ^/(.*)$ https://blosc.org/python-blosc/$1 permanent;

@datapythonista
Copy link
Collaborator

I gave a try to changing Sphinx root_doc to make index.html be the home with the content, but seems like Sphinx is buggy after doing that, and the navigation and sidebars stop showing the sidebar and the first option in the navigation. :(

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants