docs: narrative content (e.g. design decisions)

[lucascolley]

#3 (comment) suggested such an item of content, specifically regarding the decision to include constructors like asdimension rather than just leave construction to the class __init__ or __new__ methods.

I think such content would eventually belong on a documentation page, separate to the API reference. For now, one suggestion is to use this repo's wiki.

[mhvk]

Thanks for raising this! I am slightly wary about wiki -- anything not directly connected to code tends to get out of date even faster... My sense would be to set up readthedocs and ensure that we have really good docstrings...

[nstarman]

I highly recommend sybil for doing doctests. It's much more powerful, flexible, modular, and configurable than alternatives I've used.

[lucascolley]

what doctesting do you have in mind @nstarman ?

[lucascolley]

really good docstrings

I disagree that docstrings cover this issue. Docstrings should be informative about what is in the specification. Information about why the specification is as it is (likely discussing alternative unspecified options) does not belong in docstrings IMO. This is how https://data-apis.org/array-api/draft/index.html is organised.

[nstarman]

what doctesting do you have in mind @nstarman ?

Examples. E.g.

def __metrology_namespace__():
    """
    Objects conforming to the Quantity API have a `__metrology_namespace__` method. for example 

    >>> from metrology_api import MetrologyNamespace
    >>> import package
    >>> mn = package.Quantity. __metrology_namespace__()
    >>> isinstance(mn, MetrologyNamespace)
    True
"""

[lucascolley]

Examples

Sure thing 👍 I don't think that is relevant to this issue, though

[mhvk]

Indeed, the logic is better in a document - I'm mostly wary of using a wiki instead of something more closely tied to the repository.

[andrewgsavage]

Any preferences on how this should be set up? I note that the array api uses a different structure to most docs, storing each version of the standard in the repo. is that needed?

[lucascolley]

storing each version of the standard in the repo

Definitely not yet. Maybe one day, but we can cross that bridge if it appears

[nstarman]

IMO that storage choice is sub-optimal. Having RTD versions, using version branches, seems better. For one thing, it's much easier to evolve the docs and not have to fix old versions of the standard.
GH is not letting me upload an image, so let me just link to https://docs.astropy.org/en/stable/ where this layout can be seen in the lower right corner.

[andrewgsavage]

Yea that's fine with me, any preference for a theme? I suppose this issue can be closed with a markdown file and we can set up full docs later

…

On Mon, 23 Jun 2025, 23:08 Nathaniel Starkman, ***@***.***> wrote: *nstarman* left a comment (quantity-dev/metrology-apis#20) <#20 (comment)> IMO that storage choice is sub-optimal. Having RTD versions, using version branches, seems better. For one thing, it's much easier to evolve the docs and not have to fix old versions of the standard. GH is not letting me upload an image, so let me just link to https://docs.astropy.org/en/stable/ where this layout can be seen in the lower right corner. — Reply to this email directly, view it on GitHub <#20 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADEMLEHWZV5LU4NTDTX4GW33FB3FJAVCNFSM6AAAAAB72EFJQ6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSOJYGEYDIOJTGE> . You are receiving this because you commented.Message ID: ***@***.***>

[mhvk]

👍 to just using versions and letting readthedocs take care - that's easy and would seem intuitive (can always have a page that states what one should do).