Codecov Report

Merging #991 (abde151) into master (11167ca) will decrease coverage by 0.00%.
The diff coverage is 0.00%.

@@            Coverage Diff             @@
##           master     #991      +/-   ##
==========================================
- Coverage   11.27%   11.26%   -0.01%     
==========================================
  Files         629      630       +1     
  Lines       72338    72348      +10     
==========================================
- Hits         8154     8151       -3     
- Misses      64184    64197      +13     

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 11167ca...abde151. Read the comment docs.

proposed usage:

from PYME import apistatus

@apistatus.api
def some_function_we_are_going_to_maintain(...)
    # a function that we expect to be used in 3rd party code / plugins

@apistatus.internal
def _my_magic_function(...)
   # something that we do not expect to (ever) be called from external code
  # NOTE: a leading underscore will always imply @apistatus.internal, whether annotated or not
  # but is used for things that are private to a specific module/class, even within PYME. The purpose of
  # the decorator is actually for classes/functions which might represent an internal API of sorts - 
  # i.e. public within PYME, but not recommended for external use.

On the super-long time scale TODO - add a flag to the class/method which alters how APIDoc parses/formats it.

This seems like a good approach. Its presence in the code will already signal to anybody who seriously works on code what the current/intended status is - as this generally needs looking into the source code anyway. If it eventually shows up in docs good, too, but probably less essential then in the code base. Would also remind any core developer touching certain interfaces may require extra care.

I think this is a reasonable middle-ground between writing clear documentation and saying, "it's in the code, good luck". Documentation would eliminate the need for these decorators, but we probably won't document everything anytime soon.

We should definitely make sure the meaning of these flags is in the online docs.

@zacsimile - Documentation would not strictly remove the need for the decorators.

• The alternative of manually putting an API status section in each docstring would result in a lot of extra work, and would be error prone and/or not done.
• High level documentation (as might be needed) is not directly tied to the functions in question and might not track.
• People are not necessarily going to remember to read the API summary when modifying functions - to have a flag that will be immediately visible when editing a function should be very useful
• the decorator approach can be extended to a) automatically collect and summarize all functions that form part of the API and b) potentially introduce C/I checks on modifications to API functions.

I think this is worth merging. Can we also add a decorators.rst file describing this and put it under "API Documentation" in hacking.rst?

Major issue with this at present is how sphinx/numpydoc treats docstring sections which don't match it's expectations ...

looks like sphinx-doc/sphinx#8658 might have a solution ...