search

sot / chandra_aca

Chandra Aspect Camera Tools
https://sot.github.io/chandra_aca
BSD 2-Clause "Simplified" License
0 stars 0 forks source link

Convert docstrings to numpydocs format and add dark_model API docs #156

Closed taldcroft closed 1 year ago

taldcroft commented 1 year ago

Description

This uses some WIP code (https://github.com/sot/skare3_tools/pull/101) to convert from ReST format docstrings to numpydocs format. I spent some time trying to use the pyment package but found that it does not handle any docstring with inline examples.

The ReST format which is used in most Ska packages is unsatisfactory because it does not really support indicating the type of input parameters.

Rendered sphinx docs: https://icxc.harvard.edu/aspect/test_review_outputs/chandra_aca/pr156/html/

Interface impacts

None

Testing

Unit tests

Independent check of unit tests by [REVIEWER NAME]

Functional tests

Docs were built using this and are available at the URL in the description.

javierggt commented 1 year ago

I looked at the changes and they look reasonable to me.

The only thing is that the documentation ends up looking different from the current one. The reason is that, after this PR, the members of each module appears in the corresponding page, whereas the current docs only show narrative docs.

Strictly speaking, the module members should have been shown (because they are explicitly called, e.g. see https://github.com/sot/chandra_aca/blob/master/docs/aca_image.rst?plain=1#L11)), but I just prefer when API and narrative docs are separated, or at least that the API comes after the narrative. That's a matter of taste though.