Deprecate pdoc-based documentation page

[ghost]

Sphinx with an RTD theme is the current documentation system. However, a pdoc3 -based documentation page is still up, although it's not being used. This branch deprecates it:

• Removes all pdoc related instructions from makefiles and similars.
• Updates links to documentation across the repo (from docs/rtd/ to /docs/)

Still missing:

• Set up redirect from /docs/rtd to /docs/ (release CI/CD pipeline)

[codecov-commenter]

Codecov Report

Merging #982 (3134376) into develop (c31b627) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff            @@
##           develop     #982   +/-   ##
========================================
  Coverage    90.80%   90.80%           
========================================
  Files          169      169           
  Lines         4653     4653           
========================================
  Hits          4225     4225           
  Misses         428      428           

Flag	Coverage Δ
py3.8-ubuntu-latest-pandas	90.80% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update c31b627...3134376. Read the comment docs.

[ghost]

@sbrugman Would any of the solutions here for the redirect be a viable option? https://superdevresources.com/redirects-jekyll-github-pages/

[sbrugman]

@sbrugman Would any of the solutions here for the redirect be a viable option? https://superdevresources.com/redirects-jekyll-github-pages/
For the docs index page, a redirect of that kind is used.

The challenge is not having to create individual redirects for each old page, while not having access to the normal server-side tools. We could create a 404 page that, when the URL contains /rtd/, redirects to the parent folder.
e.g. https://pandas-profiling.ydata.ai/docs/master/rtd/pages/previously_existing_page.html
See this post and the github docs

[ghost]

@sbrugman Would any of the solutions here for the redirect be a viable option? https://superdevresources.com/redirects-jekyll-github-pages/
For the docs index page, a redirect of that kind is used.

The challenge is not having to create individual redirects for each old page, while not having access to the normal server-side tools. We could create a 404 page that, when the URL contains /rtd/, redirects to the parent folder. e.g. https://pandas-profiling.ydata.ai/docs/master/rtd/pages/previously_existing_page.html See this post and the github docs

I was checking with YData's infrastructure team and it's not easy to create server-side redirects given the way the website is currently set up. So, the two options I see are:

• The 404 page method you suggest.
• Suggested by @portellaa, the Sphinx extension sphinx-reredirects, which might just work via its wildcard support.

Both seem fine to me. Assuming it works, the extension would probably lead to a smoother experience. Any preference?

[sbrugman]

Sphinx-redirect is preferable, as it can be maintained without modifying the GitHub Pages config. It supports directory redirects.

[ghost]

@sbrugman Briefly played around with the extension and it doesn't exactly fit this use case without some convoluted workflows and poor generalisation if/when new pages are added (due to the way the wildcard and source matching works).

Given that all the links in the repo have been updated (apart from those eventually present in GitHub issues), the problem would mainly manifest with external links from the web. I feel it's OK to redirect those to the main page (and hopefully the new docs structure will make it easy for everyone to find what they are looking for).

In that case, from what I read on that StackOverflow page, I think a simple solution would be serving a 404.html page redirecting to the documentation's home. I think this could be achieved, in the release.yml CI pipeline, through a:

cp docs/${{ env.BRANCH_NAME }}/index.html 404.html
git add 404.html

Thoughts?

[sbrugman]

Ok, let's go with the redirect. By default we can redirect urls that contain /rtd/ to the same url where the directory is removed (using javascript) to ease the user experience for external web links.

[ghost]

@sbrugman As we agreed, given the incoming docs restructuring branch, a lot of external URLs will be broken, it doesn't make as much sense as before to do the rtd/ redirect, so we will go with the default 404 page redirecting to the docs' home.

In that case, I am marking this branch as ready for review and creating a separate one with the 404 to merge into gh-pages.