Possible reorganization of the documentation

[paganol]

The current version of the documentation is a bit messy, here are some suggestions we can implement to improve readability:

1. the scanning strategy chapter is rather long, we could move the hwp (and in general the pointing generation) in a new entry;
2. the chapter Time order simulations could be converted simple page with a general introduction and then links to single pages for dipole, scan map, noise, and (in the future) beam convolution.
3. all the systematics (non linearity, gain drift, hwp systematics, etc..) could go in a single separate chapter
4. the entry Bandpasses could go in a sub entry of the chapter Detectors, channels, and instruments

[anand-avinash]

If easily doable, I would suggest also to change the documentation theme. With the current theme I find it very difficult to navigate and infer the type, default values, etc. of the function arguments from the documentation. One such example:

[ziotom78]

Hi @anand-avinash , I agree, the look is terrible!

Do you have any example of a good alternative for our Sphinx theme? I have little experience in customizing Sphinx.

[anand-avinash]

To me, PyData sphinx theme looks better. It is the same theme used in numpy and scipy docs
https://pydata-sphinx-theme.readthedocs.io/en/stable/

[yusuke-takase]

I tried to change a document of my grasp2alm alabaster (current lbsim's docs theme) to pydata_sphinx_theme, indeed it looks better and it was not too difficult.
Basically, I just only added the pydata_sphinx_theme into the requirement by poetry add and modified docs/conf.py.

[ziotom78]

Hi all, thanks for your comments! I can work on this.

I am currently thinking of a possible way to get a reasonable outline for the manual. What do you think about the following structure?

[paganol]

Hi @ziotom78, thanks!
Few comments:

1. Probably tutorial should go after chapters 3 and 4
2. Scanning strategy is in 3 and 4, probably should go only in 4.
3. Bandpasses could be a sub section of detectors, channels, etc...
4. We could split chapter 4 in 2 chapters or in 2 sections, one for basic modules, and one for systematics