fix(api-reference): add missing info, types and <Since />
#8943
Conversation
* Add default for `page.size` and `pageSize` (see withastro/astro#11561) * Add missing Since for `page.url.first` and `page.url.last` (see withastro/astro#11176)
* Add missing properties (`rawContent`, `compiledContent` and `default`)
* Fix inaccurate types for Astro.cookies `get` and `set` methods * Add missing `merge` method for Astro.cookies (the `AstroCookies` return type could miss some documentation) * Fix inaccurate type for AstroCookie `value` I did not updated the name of the options types, but all of them should be prefixed with `Astro`. I don't know if this is deliberate or an oversight during an update. See: `packages/astro/src/core/cookies/cookies.ts`
It was deprecated but it has been removed in v2.0.0 (see withastro/astro#5707). I think it should not be displayed in the reference anymore since we are now at v4.12.1
* See withastro/astro#4986 for `site`, `generator`, `url`, `clientAddress`, `props` and `redirect` * See withastro/astro#6721 for `locals` * See withastro/astro#9021 for `preferredLocale` and `preferredLocaleList` * See withastro/astro#9101 for `currentLocale`
* See withastro/astro#7607 for the most recent exported types * See withastro/astro#6850 for `reference()` * See `packages/astro/types/content.d.ts` for `schema` type (might need a refactor) * `getDataEntryById` is missing but since `getEntryBySlug` is announced as deprecated I don't know if we should add it (so no change here)
* Add missing Since (see withastro/astro#7578 for `createContext` and `trySerializeLocals` * Add missing types (see `packages/astro/src/core/build/types.ts` and `packages/astro/src/@types/astro.ts`)
* Make Types in Internationalization section consistent with other declared functions types
✅ Deploy Preview for astro-docs-2 ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Lunaria Status Overview🌕 This pull request will trigger status changes. Learn moreBy default, every PR changing files present in the Lunaria configuration's You can change this by adding one of the keywords present in the Tracked Files
Warnings reference
|
sarah11918
added
improve documentation
|
Thank you @ArmandPhilippot , this looks great! I'm going to ask @delucis to review this one! |
There was a problem hiding this comment.
Wow, thank you @ArmandPhilippot for this amazingly thorough work! Love to see stuff like the default pagination values specified — really helpful 💜
So if you have any guidance about the formatting, I'll be happy to update this PR to make the documentation more consistent (at least in this file)! 😄
The examples in Astro Docs Docs are correct! Ideally, when there are multiple short items like Type + <Since>, these should be grouped together rather than in separate paragraphs.
You can see this style in use in our configuration reference which is generated automatically from code:
getDataEntryByIdis missing butgetEntryBySlugis marked as deprecated in the documentation (I couldn't find a reference about this) so I don't know if we should add it (I guess it is also deprecated)
Yes, if I’m not mistaken, they are both deprecated in favour of getEntry().
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
* Add "Markdown only" mention to `rawContent` and `compiledContent` * Reword the introductory line to index `MarkdownInstance` (see withastro#8943) Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
* Replace `CookieGetOptions` with `AstroCookieGetOptions` * Replace `CookieSetOptions` with `AstroCookieSetOptions` * Replace `CookieDeleteOptions` with `AstroCookieDeleteOptions` * Add links to documented types inside `Type:` information
From Astro Docs Docs, Types/Default/Since information should be in a single block (see https://contribute.docs.astro.build/reference/custom-components/#examples-1) I wrapped single information (e.g. Types) with a `<p>` tag to keep the block consistent and to help future contributors understand that the format must be the same if they add information. Also, I added an empty line after the opening `<p>` tag because of a possible parsing issue. See: 35d1f4b
|
Re: 35d1f4b the newline made sure subsequent markup is treated as Markdown IIRC. In other words the following doesn’t work: <p>
**Type:** `undefined`
</p>It renders the children as HTML directly: <p>
**Type:** `undefined`
</p>But the new line lets the Markdown parser take over again: <p>
**Type:** `undefined`
</p>Renders: <p>
<strong>Type:</strong> <code>undefined</code>
</p>
Yes, probably. I asked the team about the status of |
|
Update on |
* Add documentation about the deprecated getDataEntryById function * Fix return type for getDataEntryBySlug (this is a Promise)
We cannot use `ul` inside `p` tag so we need to make an exception when using Since and Type with overloads and separate them.
Only the argument was added in `4.13.0` so it doesn't make sense to keep it under `next()` heading. Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
* Move `next()` as subheading of `onRequest()` because it is an argument of that function * Add a `context` subheading to describe the first argument * Update `context` link to redirect to the new `context` section
* Add the `getImage` function signature * List every properties returned by the function
|
I think the previous points are all solved! While I was rereading the page, I noticed that the So I added some changes to differentiate a little the two sections:
I wonder if a link from But we have almost the same information... |
|
Nicely spotted! Yes, I’d even say now that once we merge this we could also clean up the “Generating images…” section to be more focused on the practical usage part with a link to reference for the full type details. Similarly the image component docs feel a lot like they should mostly be in reference for each prop. Maybe image docs improvement is a whole other rabbit hole best tackled in a separate PR 😁 |
|
Looking great, amazing work here! I trust Chris to make the final approval here, and will only say that I agree on scoping this PR to the api-reference page only! If you start looking on other pages, I'm sure you'll find more improvements you want to make, so let's make life easier on the translators and tackle these kinds of improvements one page at a time! 😄 |
There was a problem hiding this comment.
Woo, I think we’re pretty much there — amazing work @ArmandPhilippot! I left a couple of copy suggestions not strictly related to your changes, but thought we might as well get them in while we’re in this file.
|
Also pointing out that there's a draft API reference for Actions in #8980 , so feel free to hop into that PR and get that API reference entry up to speed from the beginning! |
The arguments are always available. It is up to the consumer to use them or not. Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
* Aligns phrasing with the new `context` subsection of `onRequest` * Makes the use of `next()` function clearer Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
|
Thanks @delucis, the I think we've covered this file. There are some missing types but adding them might be more harmful than helpful since they rely on Typescript generics:
So unless you see any other improvements, I think we're good this time! 🎉 |
There was a problem hiding this comment.
Agreed! Ready to merge — thanks again for the thorough and persistent work here @ArmandPhilippot 🙌
delucis
added
the
Merge Queue
ArmandPhilippot
deleted the
fix/api-reference-add-missing-info-types-since
branch
This PR is a follow-up to my discussion with @sarah11918 in #8929.
Description (required)
I updated
api-reference.mdxto add missing (or to update) information like:<Since />component,For this task, I tried to keep track of my references in each commit (with URLs) so that you can verify the accuracy of the information (this is why this PR has so many commits, I found it was easier to divide the file in parts).
I left out some types that seemed too complex to understand by reading the documentation. Also, I modified a type but I'm not sure its definition is clear from reading the documentation. I'll add a review comment.
If I haven't added a
<Since />component it's either because I haven't found when the property/component was added or because it dates from v1 or earlier.Additionally, I noticed some missing sections:
Astro.cookieswas described exceptmerge, I added itgetDataEntryByIdis missing butgetEntryBySlugis marked as deprecated in the documentation (I couldn't find a reference about this) so I don't know if we should add it (I guess it is also deprecated)Finally, I removed:
Astro.canonicalURLbecause it seems it was removed inv2.0.0(see Remove deprecated APIs astro#5707 and we are currently inv4.12.1)Related issues & labels (optional)
Documentation "coding" style related
While translating the doc in French and while updating this file, I noticed that some parts of the files was inconsistent, more exactly when we have
<Since />and/or**Types:**:<Since />OR**Types:**are wrapped in<p>...</p>tags, other times it is not the case<Since />AND**Types:**are both provided, sometimes they are in a block wrapped with<p>...</p>, other times they are separated (often we have a<Since />wrapped in<p>...</p>tags followed by or put after**Types:**and separated by a new line)While updating this file I wasn't sure what to do. In Astro Docs Docs, we have an example but I wasn't sure if it was a guideline or just an example.
So if you have any guidance about the formatting, I'll be happy to update this PR to make the documentation more consistent (at least in this file)! 😄