DOCS: List of functions and calling sequences

[billetd]

Documentation

Provide a list of pyDARN functions, short descriptions and calling sequences for users to quickly browse

Purpose

• new

Category

• code documentation

Details

Currently, documentation revolves along a set of tutorials for useful pyDARN functionalities such as reading/writing data, plotting, etc. These tutorials are handwritten and can be time consuming to make whenever a new feature or function is added to pyDARN.

I propose the creation of a new section of the documentation, readily available to users (e.g. on readthedocs), which will contain a simple list of pyDARN functions hyperlinked to their respective files. This list will contain the functions calling sequences and a short description of what it does.

By including this new list, pyDARN functionality which may not currently be obvious to a user (such as grabbing a single scan worth of data, getting beam/gate coordinates, etc) will be made readily visible, without having to write a tutorial for every single one. It will be simple to update whenever a new function is added to pyDARN (just add it to the list along with the functions pull request) and will act as a quick reference guide to what pyDARN can do.

An example of what I had in mind would be similar to the reference list found for the AACGMv2 python library.

For ease of creation/upkeep, using the Sphinx autodoc module will probably work best.

[mts299]

I was just thinking that I saw a pdoc is an option too that would work with our documenting style.

The type of documentation you want is called API documentation - which is why I was kind of confused about what you meant with matplotlib documentation. This was on my pyDARN many todos but got pushed to the bottom as things do haha.

Let me know if you want me to spend some time on it.,

[billetd]

@mts299 I think I've got this for now. I've managed to compile a working version of the docs using Sphinx, which works with the current markdown documentation without any re-writing needed. The autodoc module reads the docstrings which are already there, so will hopefully require minimal reconfiguring.