Skip to content

Merge and migrate Python API documents into docstring#387

Merged
lan496 merged 9 commits intospglib:developfrom
lan496:python-api-doc
Jan 10, 2024
Merged

Merge and migrate Python API documents into docstring#387
lan496 merged 9 commits intospglib:developfrom
lan496:python-api-doc

Conversation

@lan496
Copy link
Copy Markdown
Member

@lan496 lan496 commented Jan 7, 2024

This PR moves Python API documents into docstring of python/spglib/spglib.py. autodoc2 is used to generate API documents (which is compatible with myst). It will diminish the burden for document maintenance somewhat.

@atztogo Spglib uses numpy-style docstring, but autodoc2 does not support it. sphinx.ext.napoleon does not work as well. Do we use sphinx's python-domain directives instead? Autodoc2 seems to support MyST docstring with these directives.
https://sphinx-autodoc2.readthedocs.io/en/latest/quickstart.html#using-markdown-myst-docstrings

@lan496 lan496 requested a review from atztogo January 7, 2024 04:49
@lan496
Copy link
Copy Markdown
Member Author

lan496 commented Jan 7, 2024

@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Jan 7, 2024 •
edited
Loading

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (7aa3491) 83.86% compared to head (34fd27a) 83.86%.

Additional details and impacted files 
@@           Coverage Diff            @@
##           develop     #387   +/-   ##
========================================
  Coverage    83.86%   83.86%           
========================================
  Files           24       24           
  Lines         8180     8180           
========================================
  Hits          6860     6860           
  Misses        1320     1320
Flag Coverage Δ
c_api 77.59% <ø> (ø)
fortran_api 56.15% <ø> (ø)
python_api 80.38% <ø> (ø)
unit_tests 1.24% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@lan496
Copy link
Copy Markdown
Member Author

lan496 commented Jan 7, 2024

I am not satisfied with the generated API docs because they are too long (for example, get_symmetry_dataset). That being said, I will merge this PR if it is acceptable. I think TypedDict for a returned dictionary will improve the readability without losing backward compatibility.

@lan496 lan496 mentioned this pull request Jan 7, 2024
Closed
4 tasks
atztogo
atztogo approved these changes Jan 7, 2024
View reviewed changes
Copy link
Copy Markdown
Collaborator

@atztogo atztogo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @lan496 for a lot of work. I installed autodoc2 using pip and I could generate the documentation using sphinx-autobuild. It looks very good. Originally I never thought spglib python API would be used so much by people. So I made it to be similar to the C functions and the design is not pythonic. Those can be renovated at some point in the future if it will be worth to do it.

@atztogo
Copy link
Copy Markdown
Collaborator

atztogo commented Jan 7, 2024

@lan496, any docstring style is fine to me.

@LecrisUT LecrisUT self-requested a review January 7, 2024 06:55
@lan496 lan496 marked this pull request as ready for review January 7, 2024 23:04
LecrisUT
LecrisUT requested changes Jan 8, 2024
View reviewed changes
@LecrisUT
Copy link
Copy Markdown
Collaborator

LecrisUT commented Jan 8, 2024

Do we use sphinx's python-domain directives instead?

*sphinx-style (it can be used for C/C++ code as well), and yes, I would say it's a better interface and rst/md agnostic. 👍 for that format

@lan496 lan496 requested a review from LecrisUT January 8, 2024 11:12
@LecrisUT LecrisUT mentioned this pull request Jan 8, 2024
Open
LecrisUT
LecrisUT reviewed Jan 8, 2024
View reviewed changes
@lan496 @LecrisUT
Update doc/api/develop.md
2a42574 
Co-authored-by: Cristian Le <[email protected]>
LecrisUT
LecrisUT reviewed Jan 10, 2024
View reviewed changes
@lan496 lan496 merged commit 50a2c3f into spglib:develop Jan 10, 2024
@atztogo
Copy link
Copy Markdown
Collaborator

atztogo commented Jan 10, 2024

Thanks @lan496, @LecrisUT!

@lan496 lan496 mentioned this pull request Jan 10, 2024
Merged
@LecrisUT LecrisUT added this to the 2.3 milestone Jan 25, 2024
@chenrui333 chenrui333 mentioned this pull request Jan 28, 2024
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@atztogo atztogo atztogo approved these changes

@LecrisUT LecrisUT LecrisUT approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

2.3

Development

Successfully merging this pull request may close these issues.

4 participants

@lan496 @codecov-commenter @atztogo @LecrisUT