-
Notifications
You must be signed in to change notification settings - Fork 2
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
DOC: initial documentation #50
Conversation
@nstarman I have opted here to use the summary-style tables for properties and methods in the protocols, which is much more compact than the full form. I also decided against creating individual pages for each method, because they contain almost no added value. We should explain the deal with input and output array types in prose in the "how to use" section for users. Other than that, I would argue that no method has a signature that warrants more than the one line summary shown in the table. Should any set of functions require proper explanation (e.g. the meaning of all distances), I believe those should go on prose pages with a proper explanation (e.g. "Distance functions"), and not the API docs. These should always remain short and with only the necessary information. |
45a3926
to
b8b111d
Compare
Codecov Report
📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more @@ Coverage Diff @@
## main #50 +/- ##
==========================================
- Coverage 82.49% 82.24% -0.25%
==========================================
Files 13 13
Lines 377 383 +6
==========================================
+ Hits 311 315 +4
- Misses 66 68 +2
Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here. |
@nstarman I managed to hack autosummary to generate something close to what I originally had in mind: a flat list of all methods and properties, and the protocol hierarchy, all linking to the same documentation page with a single source of truth. The autosummary hack is horrible, but I don't see another way. |
The docs look great! In particular, getting the "On this page" to not include the prefix is a major improvement. I'll do a more detailed review and contribute some more docs, probably in the form of docstrings, but a few notes for now:
|
Failing because #53 is not merged. |
docs/tests/test_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's keep this in the test suite. It s good to track which libraries support float addition, for the discussion of the input type.
Oh no. Rebasing muddled the commit history. |
d1a424e
to
2760095
Compare
@nstarman Ok, I think that this PR is ready on the technical side, it only needs some more content. Do you want to merge first or do everything in this PR? |
e1913fd
to
0b6c4ec
Compare
Let's merge first! We'll get the docs as solid as possible in quick followups. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Docs look great!
if parent is cosmo: | ||
_, _, membername = name.rpartition(".") | ||
protocols = [ | ||
f"{cls.__qualname__}.{membername}" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It looks like this could be made a back-link to the parent Protocol?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For a followup PR.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Description
This pull request is to create the initial documentation skeleton for the Cosmology API.
PR Checklist
CHANGES.rst
file. See existing changelog for examples.docs
folder.