A collection of things that should be improved in the docs (to follow #196 where we want to improve and simplify the introductory examples):
-
Dedicated top-level page on working with ND-arrays. It is discussed in various places especially in the section on writing: https://libasdf.readthedocs.io/en/latest/usage/writing.html#adding-ndarrays But it's an important enough concept that it merits more narrative documentation on the asdf_ndarray_t structure, how to read it, how to build it, etc. as well as setting different properties (compression, inlined, etc.)
-
Clean up structure of existing header API documentation. Hawkmoth (which is used to generate the Sphinx docs from C) supports sub-headings within individual headers, for docs generated from those headers. That's already used to some good effect to organize the API documentation for asdf/file.h (though could use a heading for asdf_file_t). However, the other headers mostly aren't organized into sub-sections so you get an unwieldy ToC that looks like this:
So will be good to add logical organization to the ToC for the other headers as well.
- Fill out some undocumented functions. There are a number of
.. todo:: to be taken care of.
Out of scope for now: full documentation of "lower-level" APIs (namely, parser event handling). Right now I don't think there is a strong use case for this, though it's available if someone wants to dig into the internals. Maybe worth just slightly improving the "TODO: Document lower-level APIs" to mention what these "lower-level APIs" are, that they exist, where to find them.
A collection of things that should be improved in the docs (to follow #196 where we want to improve and simplify the introductory examples):
Dedicated top-level page on working with ND-arrays. It is discussed in various places especially in the section on writing: https://libasdf.readthedocs.io/en/latest/usage/writing.html#adding-ndarrays But it's an important enough concept that it merits more narrative documentation on the
asdf_ndarray_tstructure, how to read it, how to build it, etc. as well as setting different properties (compression, inlined, etc.)Clean up structure of existing header API documentation. Hawkmoth (which is used to generate the Sphinx docs from C) supports sub-headings within individual headers, for docs generated from those headers. That's already used to some good effect to organize the API documentation for
asdf/file.h(though could use a heading forasdf_file_t). However, the other headers mostly aren't organized into sub-sections so you get an unwieldy ToC that looks like this:So will be good to add logical organization to the ToC for the other headers as well.
.. todo::to be taken care of.Out of scope for now: full documentation of "lower-level" APIs (namely, parser event handling). Right now I don't think there is a strong use case for this, though it's available if someone wants to dig into the internals. Maybe worth just slightly improving the "TODO: Document lower-level APIs" to mention what these "lower-level APIs" are, that they exist, where to find them.