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. |
ntessore
force-pushed
the
nt/docs
branch
2 times, most recently
from
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.
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. |
ntessore
force-pushed
the
nt/docs
branch
3 times, most recently
from
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? |
ntessore
force-pushed
the
nt/docs
branch
2 times, most recently
from
e1913fd
to
0b6c4ec
Compare
|
Let's merge first! We'll get the docs as solid as possible in quick followups. |
| if parent is cosmo: | ||
| _, _, membername = name.rpartition(".") | ||
| protocols = [ | ||
| f"{cls.__qualname__}.{membername}" |
There was a problem hiding this comment.
It looks like this could be made a back-link to the parent Protocol?
Description
This pull request is to create the initial documentation skeleton for the Cosmology API.
PR Checklist
CHANGES.rstfile. See existing changelog for examples.docsfolder.