Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 5 commits into from
Sep 13, 2023

Conversation

taldcroft
Copy link
Member

@taldcroft taldcroft commented Aug 25, 2023

Description

This uses some WIP code (sot/skare3_tools#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

  • Mac

Independent check of unit tests by [REVIEWER NAME]

  • [PLATFORM]:

Functional tests

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

@taldcroft taldcroft changed the title WIP: Convert docstrings to numpydocs format and add dark_model API docs Convert docstrings to numpydocs format and add dark_model API docs Aug 27, 2023
@taldcroft taldcroft requested a review from javierggt August 27, 2023 10:55
@javierggt
Copy link
Contributor

javierggt commented Sep 13, 2023

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.

@taldcroft taldcroft merged commit b726383 into master Sep 13, 2023
@taldcroft taldcroft deleted the numpydocs branch September 13, 2023 18:18
@javierggt javierggt mentioned this pull request Oct 4, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants