Initialize github pages

[qiaojunfeng]

Some commits to bootstrap the docs versioning.

Once this is merged, docs will be automatically deployed using github actions in #484, whenever there is a new release (e.g. v4.0.0) on github.

This is draft since I need to rebase the PR after the merge of #484.

[LecrisUT]

RTD supports mkdocs ¹. I highly recommend not to go with GH-pages and instead use RTD. If there are any concerns I am happy to discuss them.

@giovannipizzi @qiaojunfeng

Footnotes

1. https://docs.readthedocs.io/en/stable/config-file/v2.html ↩

[qiaojunfeng]

RTD supports mkdocs 1. I highly recommend not to go with GH-pages and instead use RTD. If there are any concerns I am happy to discuss them.

@giovannipizzi @qiaojunfeng

Footnotes

1. https://docs.readthedocs.io/en/stable/config-file/v2.html ↩

RTD is OK, it's just I don't want to see advertisements on the doc webpages. I think for the free version, we cannot git rid of ads.

Could you explain in detail the downsides of gh-pages than RTD? If RTD is much better in terms of some features, I can try RTD and see if people can tolerate the ads.

[LecrisUT]

Thanks for sharing the concerns

RTD is OK, it's just I don't want to see advertisements on the doc webpages

This is disableable, here is the instructions:

The gold membership is 5$/month.

Could you explain in detail the downsides of gh-pages than RTD? If RTD is much better in terms of some features, I can try RTD and see if people can tolerate the ads.

• RTD supports versioning automatically, including adding/removing versions
• Visibility and SEO
• RTD can be run on pull requests
• Reduced maintenance, e.g. python versioning and guaranteeing compatibility
• RTD adds additional default options to optimize search and other things we should not think about
• Some projects can use RTD API to display pop-up displays of cross-projects, and other nice features
• GH-pages, will get messy for git cloning

[qiaojunfeng]

Thanks for the info!

• RTD supports versioning automatically, including adding/removing versions

Yes, that's one advantage, with gh-pages I need to use mike to do the versioning for mkdocs, which is also quite nice but we need to store them in the gh-pages branch.

• Visibility and SEO
• RTD adds additional default options to optimize search and other things we should not think about

I have some other projects that are using gh-pages, and they can be indexed as the topmost one by google/bing/duckduckgo in few days. For a much more widely used repo like wannier90, I wouldn't worry too much.

• RTD can be run on pull requests

This is nice to have.

• Reduced maintenance, e.g. python versioning and guaranteeing compatibility

I am using GitHub workflows for docs deployment upon each wannier90 release, so both are fine.

• Some projects can use RTD API to display pop-up displays of cross-projects, and other nice features

OK.

• GH-pages, will get messy for git cloning

Indeed this is the biggest disadvantage of gh-pages, for now all the html+js are around 7.8MB for each release. This will increase the size of the repo in the long term.

So in the end it's weather we want to remove ads or reduce the size of the repo.

I will create a test doc on RTD to see it in real, then we decide which one we want.