Documentation rework

[zerothi]

We need to rework the documentation. This has been a long-standing wish, by everybody... :)

The purpose of this issue is to track documentation progress, and to propose new documentation ideas.

It may take a long time to finalize, due to the limited amount of time we have, but I hope that as many people can join in when we have a good picture of things, and contribute content.

This issue directly influences these issues:

• #638
• #674
• #632
• #455

Here is a list of things that can be tracked, individually

• [ ] The documentation needs to be more tutorial/guide focused
  • [ ] I kind of like the pandas site based on pydata-sphinx-theme which has nice blocks here and there (can be done using only sphinx-design)
  • [ ] Should we change theme? I know a lot of people really like RFD, but I have grown fond of the sphinx-book-theme (pandas uses pydata-sphinx-theme which is based on sphinx-book-theme.
  • We need to create some quick overview guides, here some suggestions:
    • [ ] Quick 10 minute introduction of what sisl can do for post-processing DFT data
    • [ ] Quick 10 minute introduction of what sisl can do for tight-binding calculations
    • [ ] In-depth Geometry class focus, how to manipulate, sort, use categories, etc.
    • [ ] In-depth SparseOrbital class focus, how to append, add, sub etc. It should be made clear here that all of these methods adheres to all Hamiltonian, DensityMatrix etc.
    • [ ] In-depth tutorial on how to access and see what can be read from Sile's.
    • Others? Please chip in so we can complete the list.
• [ ] Re-structure the API pages Have a look at other codes API structure, there is a lot of glue text to link the sections together, sisl misses that completely.
• [ ] Should we go and use the ipython directives, instead of nbsphinx?
  • ipython advantages includes, better search functionality, smaller, and faster documentation build times It also has the more familiar sphinx directives which can be used directly in the code.
  • nbsphinx advantages includes, direct download of the notebook (really nice), it can still be searched, but the notebooks has some problems creating links to the API documentation, which is really annoying. (I don't know if this can be fixed somehow)

The working plan would be:

1. Discuss the above details, the more feedback from devs/users the better.
2. Once we have agreed on what to do (the above list will be edited throughout the discussion) we can start doing stuff (no sooner!)
3. Wait for #665, #393 and #668 to be merged.
4. Ping the community for help!
5. Start doing work :rocket: