updates API reference

[alexhroom]

Hi there,
I am currently using orsopy to integrate .ort file parsing to python-RAT, a package for analysing and fitting reflectivity calculation models.

This package is really smooth and simple to integrate and has almost every feature I've needed, with the biggest time-sink for me being that it's almost entirely undocumented, aside from the basic fileio stuff!

I have updated the reference using sphinx-apidoc with the command:
sphinx-apidoc -d 1 -M -o ./docs/api/ ./orsopy "*/tests/*"

which generates reference for the entire package except for the test folders.

This PR:

• creates API reference for the rest of the package
• moves the blurb about fileio from the docs to the module docstring so that sphinx-apidoc can just grab it from the source code
• adds sphinx-rtd-theme to the requirements (it's required to build the docs but it wasn't listed!)

[andyfaff]

Thanks for the contribution.
I don't think it should be necessary to add this number of files though. Is it possible to do from the individual toplevel modules, i.e. orsopy.fileio, orsopy.slddb, etc. I think pretty much all of the useful functions are all in __all__ in the toplevel modules, which mean they get autodocced, so there's no need for orsopy.fileio.reduction, etc.

Also, while tools like sphinx-apidoc can be useful it's included files like orsopy.fileio.typing_backport, which don't need to be documented.

[alexhroom]

@andyfaff fair enough: I only did it with all the submodules in separate files because that's how it is in the current docs. Happy to combine them!

sphinx-apidoc has the ability to exclude patterns (like I'd done with excluding */tests/*). I'd personally argue that all of the API should be documented, even internal parts (developers might also want to read the docs rather than digging through source code!), but otherwise if you give me a list of submodules you don't think should be included in the docs I'm happy to do so.

[aglavic]

Thanks @alexhroom, any contribution to the project is welcome. I didn't have time so far to even look at out documentation. But it seems we never referenced to the ORSO website for the file format, probably with the assumption that people would come from there toe orsopy. I think a back reference should be added as well.

[alexhroom]

@aglavic have added a back reference to the docstring for the orsopy.fileio module, which is displayed on the fileio reference page :)