Feat: allow user pass config in python in addition to env variable

[Beforerr]

Also pass kwargs to load from instrument loading

[jameswilburlewis]

This seems like it should work well. Before I merge it, would you mind also updating the other load routines: state(), slp(), ssc() and ssc_pre() in spacecraft/state_tools, and esa(), esd(), gmom(), mom(), and sst() in spacecraft/particles?

It would also be nice to add a test in tests/tests.py to exercise the feature for one of the load routines.

[Beforerr]

Would do. Also I would like to avoid repeating big chunks of docstrings across multiple functions.

An example to do it. What do you think?

SHARED_DOC = """
Parameters
----------
x : int
   ...
y : int
   ...
"""

def func1(x, y):
    """Base docstring."""
    pass

# Modify docstring
func1.__doc__ += SHARED_DOC

[jameswilburlewis]

The amount repetition between docstrings for load routines is annoying, no doubt about that! But it's necessary because our main documentation repository, pyspedas.readthdocs.io, auto-generates a lot of its comments using the docstrings.
In our docs/source directory, we have a lot of rst files with contents like this:

Fluxgate magnetometer (FGM)

.. autofunction:: pyspedas.projects.themis.fgm

Example
^^^^^^^^^

.. code-block:: python

import pyspedas
from pyspedas import tplot
fgm_vars = pyspedas.projects.themis.fgm(probe='d', trange=['2013-11-5', '2013-11-6'])
tplot(['thd_fgs_btotal', 'thd_fgs_gse'])

.. image:: _static/themis_fgm.png
:align: center
:class: imgborder

Search-coil magnetometer (SCM)

.. autofunction:: pyspedas.projects.themis.scm

Example
^^^^^^^^^

.. code-block:: python

import pyspedas
from pyspedas import tplot
scm_vars = pyspedas.projects.themis.scm(probe='d', trange=['2013-11-5', '2013-11-6'])
tplot(['thd_scf_btotal', 'thd_scf_gse'])

.. image:: _static/themis_scm.png
:align: center
:class: imgborder

Electric Field Instrument (EFI)

.. autofunction:: pyspedas.projects.themis.efi

And here's how it looks on readthedocs:
https://pyspedas.readthedocs.io/en/latest/themis.html

I don't see a way to ensure that readthedocs has complete documentation, without also duplicating a lot of content in docstrings.

[Beforerr]

Hi @jameswilburlewis Sphinx will work with no problem as it will pick up the updated docstring as long as the modification happens before or during the module import. (I updated the example above and test that it works).

Also I feel like we could make the shared keyword documentation in the begining of the project page so that user can know the commonly supported keywords without wondering if specific functions support that.

[jameswilburlewis]

Oh, I see! Your edited example has the "Parameters" heading in the SHARED_DOC definition. But we'd probably want the more specific parameters listed ahead of the shared parameters, so SHARED_DOC might have to be interpolated into the middle of the docstring somehow. And Sphinx is extremely picky about indentation and blank lines, so having the docstring split into two parts might make it harder to figure out formatting issues. But, maybe it could be made to work.

How do you think it might work with a mission like goes, where the individual load routines are using pyspedas.utilities.pyspedas_functools.better_partial() to wrap a single master load routine?