Documentation appearance

[pgrigorev]

First of all I would like to thank everyone for their contributions to the code and documentation. I think we managed to make impressive improvements in a very short period of time. 🚀
This is an issue to summarise current problems with documentation and share suggestions how to improve it. Please let me know what you think. This goes far beyond to what is needed for JOSS submission review, and rather aims to plan the work in the future.

If I google matscipy I do not se the the documentation page, except an outdated version hosted on readthedocs. It shows github as the first result though, so not too bad. Googling matscipy documentaiton shows the correct link as matscipy devel documentation, however it also shows few outdated pages. It looks like this:

Would it be possible to remove outdated documentations pages?

• https://matscipy.readthedocs.io/en/latest/
• https://libatoms.github.io/matscipy/matscipy.html

The last one seems strange since it is hosted in the same place.

Do we really need to call it devel documentation? do we plan to make a release version? It is a bit confusing.

I tried to use PyData sphinx theme to generate the docs and the results looked pretty good. This theme is used by plenty of scientific python packages so people should be familiar with it. Here are couple of screenshots of how it looks without any changes to the source files.

Regardless if we decide to switch the theme or not, I think we should change the index page. At the moment it is a copy of the readme file full of technical information. I think we can come up with something a bit more encouraging. I can propose a couple of versions if you agree.

We have plenty of warnings raised during building of API documentation, if we want to fix it, we should agree on rather strict standards for the docstrings.

Finally, I think we should come up with a logo. It is a challenging task, so any proposals are wellcome. Maybe some brainstorming will help. :)
Thank you!

[pastewka]

Hi @pgrigorev - those are all good comments. Note that I no longer have access to my readthedocs account (because I no longer have access to the email address), but I just contacted them about this. Let's hope they resolve it quickly. Will then delete that old documentation.

Will also switch to the PyData sphinx scheme.

If you can make a suggestion for the landing page, that would be fantastic.

[pastewka]

Hi @pgrigorev - I've deleted the project on readthedocs. The link no longer works but it will probably take a while until it disappears from Google searches.

I've also tested the PyData theme. While I agree that it looks good (fresh and better), I found navigation harder. It was more difficult for me to understand what the table of contents looks like. That can probably be configured somehow. Feel free to make a suggestion and open a PR on it.

[pgrigorev]

Hi @pastewka, this is great that you managed to delete the readthedocs version of the documentation. I agree with you that navigation was a bit off in PyData theme. I will play with the settings and make a suggestion next week.