fermiPy / fermipy

Fermi-LAT Python Analysis Framework
http://fermipy.readthedocs.org/
BSD 3-Clause "New" or "Revised" License
51 stars 53 forks source link

Add __all__ to clarify public API #53

Closed cdeil closed 5 years ago

cdeil commented 8 years ago

I'm starting to think about how to move parts of Fermipy (specifically the HEALPix map class) to Gammapy and how to replace parts of Fermipy code by equivalent Gammapy code (specifically the WCS based maps and cube class).

@woodmd - One thing that would help a little would be if you make it clear what you consider to be part of the public Fermipy API (where changes are unwelcome or a deprecation procedure is needed) and what you consider private implementation details.

E.g. I guess this is private: http://fermipy.readthedocs.io/en/latest/fermipy.html#fermipy.skymap.make_coadd_wcs

and here should be some things that are public? http://fermipy.readthedocs.io/en/latest/fermipy.html#fermipy-tsmap-module (if no, this could be removed from the Sphinx API docs)

The usual way to declare the public API is to add __all__ lists at the top of each file, e.g. at the top of fermipy/batch.py you could add:

__all__ = [
    'check_log',
    'get_lsf_status',
    'dispatch_jobs',
]

The Sphinx automodapi directive then usually looks at these __all__ lists when generating the API docs: https://github.com/fermiPy/fermipy/blame/master/docs/fermipy.rst

I wanted to add the __all__ lists while working on #51 , but then noticed that I often don't know what is / isn't public or private in Fermipy. @woodmd - Could you please do this after #51 is merged?

woodmd commented 8 years ago

Ok I can start having a look at this next week.