Skip to content
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.

Sign up for GitHub

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

[docs-infra] Add configurable jsdoc host variable #42472

Merged
merged 7 commits into from
Jun 7, 2024
Merged

[docs-infra] Add configurable jsdoc host variable #42472

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ad7a0df
added configurable jsdoc link host variable
Jun 1, 2024
166b78a
Update packages/api-docs-builder-core/baseUi/projectSettings.ts
tonygravell Jun 3, 2024
cc5c8c0
Update packages/api-docs-builder-core/materialUi/projectSettings.ts
tonygravell Jun 3, 2024
d093cf1
run script
alexfauquette Jun 4, 2024
6c5acfa
Merge remote-tracking branch 'upstream/next' into tonygravell-update-…
alexfauquette Jun 4, 2024
f3806ca
fix prettier
alexfauquette Jun 4, 2024
f619823
update comment
alexfauquette Jun 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions packages/api-docs-builder-core/baseUi/projectSettings.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,4 +43,6 @@ export const projectSettings: ProjectSettings = {
translationPagesDirectory: 'docs/translations/api-docs-base',
generateClassName: generateUtilityClass,
isGlobalClassName: isGlobalState,
// #major-version-switch
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mnajdova is #major-version-switch the correct flag? I don't know if we have another flag for it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#default-branch-switch is much more used, honestly first time I see the #major-version-switch :)

Copy link
Member

@alexfauquette alexfauquette Jun 6, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Come from here. I will harmonize it 👍

baseApiUrl: 'https://next.mui.com',
};
2 changes: 2 additions & 0 deletions packages/api-docs-builder-core/materialUi/projectSettings.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,6 @@ export const projectSettings: ProjectSettings = {
translationPagesDirectory: 'docs/translations/api-docs',
generateClassName: generateUtilityClass,
isGlobalClassName: isGlobalState,
// #major-version-switch
baseApiUrl: 'https://next.mui.com',
};
10 changes: 7 additions & 3 deletions packages/api-docs-builder/ApiBuilders/ComponentApiBuilder.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,8 +150,12 @@ export async function computeApiDescription(
* *
* * - [Icon API](https://mui.com/api/icon/)
*/
async function annotateComponentDefinition(api: ReactApi, componentJsdoc: Annotation) {
const HOST = 'https://mui.com';
async function annotateComponentDefinition(
api: ReactApi,
componentJsdoc: Annotation,
projectSettings: ProjectSettings,
) {
const HOST = projectSettings.baseApiUrl ?? 'https://mui.com';

const typesFilename = api.filename.replace(/\.js$/, '.d.ts');
const fileName = path.parse(api.filename).name;
Expand Down Expand Up @@ -855,7 +859,7 @@ export default async function generateComponentApi(
: !skipAnnotatingComponentDefinition
) {
// Add comment about demo & api links (including inherited component) to the component file
await annotateComponentDefinition(reactApi, componentJsdoc);
await annotateComponentDefinition(reactApi, componentJsdoc, projectSettings);
}
}

Expand Down
10 changes: 7 additions & 3 deletions packages/api-docs-builder/ApiBuilders/HookApiBuilder.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,8 +111,12 @@ export interface ReactApi extends ReactDocgenApi {
* *
* * - [useButton API](https://mui.com/base-ui/api/use-button/)
*/
async function annotateHookDefinition(api: ReactApi, hookJsdoc: Annotation) {
const HOST = 'https://mui.com';
async function annotateHookDefinition(
api: ReactApi,
hookJsdoc: Annotation,
projectSettings: ProjectSettings,
) {
const HOST = projectSettings.baseApiUrl ?? 'https://mui.com';

const typesFilename = api.filename.replace(/\.js$/, '.d.ts');
const fileName = path.parse(api.filename).name;
Expand Down Expand Up @@ -613,7 +617,7 @@ export default async function generateHookApi(
await generateApiJson(apiPagesDirectory, reactApi);

// Add comment about demo & api links to the component hook file
await annotateHookDefinition(reactApi, hookJsdoc);
await annotateHookDefinition(reactApi, hookJsdoc, projectSettings);
}

return reactApi;
Expand Down
4 changes: 4 additions & 0 deletions packages/api-docs-builder/ProjectSettings.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,4 +99,8 @@ export interface ProjectSettings {
* Determines if a given slot or state is a global state
*/
isGlobalClassName: (slotOrState: string) => boolean;
/**
* Determines the base API URL for generated JSDocs
*/
baseApiUrl?: string;
}
4 changes: 2 additions & 2 deletions packages/mui-base/src/FormControl/useFormControlContext.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ import { FormControlContext } from './FormControlContext';
*
* Demos:
*
* - [Form Control](https://mui.com/base-ui/react-form-control/#hook)
* - [Form Control](https://next.mui.com/base-ui/react-form-control/#hook)
*
* API:
*
* - [useFormControlContext API](https://mui.com/base-ui/react-form-control/hooks-api/#use-form-control-context)
* - [useFormControlContext API](https://next.mui.com/base-ui/react-form-control/hooks-api/#use-form-control-context)
*/
export function useFormControlContext(): UseFormControlContextReturnValue | undefined {
return React.useContext(FormControlContext);
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/unstable_useModal/useModal.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,11 @@ const defaultManager = new ModalManager();
*
* Demos:
*
* - [Modal](https://mui.com/base-ui/react-modal/#hook)
* - [Modal](https://next.mui.com/base-ui/react-modal/#hook)
*
* API:
*
* - [useModal API](https://mui.com/base-ui/react-modal/hooks-api/#use-modal)
* - [useModal API](https://next.mui.com/base-ui/react-modal/hooks-api/#use-modal)
*/
export function useModal(parameters: UseModalParameters): UseModalReturnValue {
const {
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/unstable_useNumberInput/useNumberInput.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,11 +36,11 @@ export function getInputValueAsString(v: string): string {
*
* Demos:
*
* - [Number Input](https://mui.com/base-ui/react-number-input/#hook)
* - [Number Input](https://next.mui.com/base-ui/react-number-input/#hook)
*
* API:
*
* - [useNumberInput API](https://mui.com/base-ui/react-number-input/hooks-api/#use-number-input)
* - [useNumberInput API](https://next.mui.com/base-ui/react-number-input/hooks-api/#use-number-input)
*/
export function useNumberInput(parameters: UseNumberInputParameters): UseNumberInputReturnValue {
const {
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useAutocomplete/useAutocomplete.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -341,11 +341,11 @@ export type AutocompleteGetTagProps = ({ index }: { index: number }) => {
*
* Demos:
*
* - [Autocomplete](https://mui.com/base-ui/react-autocomplete/#hook)
* - [Autocomplete](https://next.mui.com/base-ui/react-autocomplete/#hook)
*
* API:
*
* - [useAutocomplete API](https://mui.com/base-ui/react-autocomplete/hooks-api/#use-autocomplete)
* - [useAutocomplete API](https://next.mui.com/base-ui/react-autocomplete/hooks-api/#use-autocomplete)
*/
export function useAutocomplete<
Value,
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useBadge/useBadge.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ import { UseBadgeParameters, UseBadgeReturnValue } from './useBadge.types';
*
* Demos:
*
* - [Badge](https://mui.com/base-ui/react-badge/#hook)
* - [Badge](https://next.mui.com/base-ui/react-badge/#hook)
*
* API:
*
* - [useBadge API](https://mui.com/base-ui/react-badge/hooks-api/#use-badge)
* - [useBadge API](https://next.mui.com/base-ui/react-badge/hooks-api/#use-badge)
*/
export function useBadge(parameters: UseBadgeParameters): UseBadgeReturnValue {
const {
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useButton/useButton.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@ import { MuiCancellableEvent } from '../utils/MuiCancellableEvent';
*
* Demos:
*
* - [Button](https://mui.com/base-ui/react-button/#hook)
* - [Button](https://next.mui.com/base-ui/react-button/#hook)
*
* API:
*
* - [useButton API](https://mui.com/base-ui/react-button/hooks-api/#use-button)
* - [useButton API](https://next.mui.com/base-ui/react-button/hooks-api/#use-button)
*/
export function useButton(parameters: UseButtonParameters = {}): UseButtonReturnValue {
const {
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useDropdown/useDropdown.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@ import { dropdownReducer } from './dropdownReducer';
*
* Demos:
*
* - [Menu](https://mui.com/base-ui/react-menu/#hooks)
* - [Menu](https://next.mui.com/base-ui/react-menu/#hooks)
*
* API:
*
* - [useDropdown API](https://mui.com/base-ui/react-menu/hooks-api/#use-dropdown)
* - [useDropdown API](https://next.mui.com/base-ui/react-menu/hooks-api/#use-dropdown)
*/
export function useDropdown(parameters: UseDropdownParameters = {}) {
const { defaultOpen, onOpenChange, open: openProp, componentName = 'useDropdown' } = parameters;
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useInput/useInput.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@ import {
*
* Demos:
*
* - [Input](https://mui.com/base-ui/react-input/#hook)
* - [Input](https://next.mui.com/base-ui/react-input/#hook)
*
* API:
*
* - [useInput API](https://mui.com/base-ui/react-input/hooks-api/#use-input)
* - [useInput API](https://next.mui.com/base-ui/react-input/hooks-api/#use-input)
*/
export function useInput(parameters: UseInputParameters = {}): UseInputReturnValue {
const {
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useMenu/useMenu.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,11 @@ const FALLBACK_MENU_CONTEXT: DropdownContextValue = {
*
* Demos:
*
* - [Menu](https://mui.com/base-ui/react-menu/#hooks)
* - [Menu](https://next.mui.com/base-ui/react-menu/#hooks)
*
* API:
*
* - [useMenu API](https://mui.com/base-ui/react-menu/hooks-api/#use-menu)
* - [useMenu API](https://next.mui.com/base-ui/react-menu/hooks-api/#use-menu)
*/
export function useMenu(parameters: UseMenuParameters = {}): UseMenuReturnValue {
const {
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useMenuButton/useMenuButton.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@ import { extractEventHandlers } from '../utils';
*
* Demos:
*
* - [Menu](https://mui.com/base-ui/react-menu/#hooks)
* - [Menu](https://next.mui.com/base-ui/react-menu/#hooks)
*
* API:
*
* - [useMenuButton API](https://mui.com/base-ui/react-menu/hooks-api/#use-menu-button)
* - [useMenuButton API](https://next.mui.com/base-ui/react-menu/hooks-api/#use-menu-button)
*/
export function useMenuButton(parameters: UseMenuButtonParameters = {}): UseMenuButtonReturnValue {
const { disabled = false, focusableWhenDisabled, rootRef: externalRef } = parameters;
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useMenuItem/useMenuItem.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,11 +34,11 @@ const FALLBACK_MENU_CONTEXT: DropdownContextValue = {
*
* Demos:
*
* - [Menu](https://mui.com/base-ui/react-menu/#hooks)
* - [Menu](https://next.mui.com/base-ui/react-menu/#hooks)
*
* API:
*
* - [useMenuItem API](https://mui.com/base-ui/react-menu/hooks-api/#use-menu-item)
* - [useMenuItem API](https://next.mui.com/base-ui/react-menu/hooks-api/#use-menu-item)
*/
export function useMenuItem(params: UseMenuItemParameters): UseMenuItemReturnValue {
const {
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useMenuItem/useMenuItemContextStabilizer.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@ import { ListContext, ListContextValue, ListItemState } from '../useList';
*
* Demos:
*
* - [Menu](https://mui.com/base-ui/react-menu/#hooks)
* - [Menu](https://next.mui.com/base-ui/react-menu/#hooks)
*
* API:
*
* - [useMenuItemContextStabilizer API](https://mui.com/base-ui/react-menu/hooks-api/#use-menu-item-context-stabilizer)
* - [useMenuItemContextStabilizer API](https://next.mui.com/base-ui/react-menu/hooks-api/#use-menu-item-context-stabilizer)
*
* @param id - The id of the MenuItem. If undefined, it will be generated with useId.
* @returns The stable ListContext value and the id of the MenuItem.
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useOption/useOption.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@ import { EventHandlers } from '../utils/types';
*
* Demos:
*
* - [Select](https://mui.com/base-ui/react-select/#hooks)
* - [Select](https://next.mui.com/base-ui/react-select/#hooks)
*
* API:
*
* - [useOption API](https://mui.com/base-ui/react-select/hooks-api/#use-option)
* - [useOption API](https://next.mui.com/base-ui/react-select/hooks-api/#use-option)
*/
export function useOption<Value>(params: UseOptionParameters<Value>): UseOptionReturnValue {
const { value, label, disabled, rootRef: optionRefParam, id: idParam } = params;
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useOption/useOptionContextStabilizer.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ import { ListContext, ListContextValue } from '../useList';
*
* Demos:
*
* - [Select](https://mui.com/base-ui/react-select/#hooks)
* - [Select](https://next.mui.com/base-ui/react-select/#hooks)
*
* API:
*
* - [useOptionContextStabilizer API](https://mui.com/base-ui/react-select/hooks-api/#use-option-context-stabilizer)
* - [useOptionContextStabilizer API](https://next.mui.com/base-ui/react-select/hooks-api/#use-option-context-stabilizer)
*
* @param value - The value of the Option.
* @returns The stable ListContext value.
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useSelect/useSelect.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,11 +56,11 @@ function defaultFormValueProvider<OptionValue>(
*
* Demos:
*
* - [Select](https://mui.com/base-ui/react-select/#hooks)
* - [Select](https://next.mui.com/base-ui/react-select/#hooks)
*
* API:
*
* - [useSelect API](https://mui.com/base-ui/react-select/hooks-api/#use-select)
* - [useSelect API](https://next.mui.com/base-ui/react-select/hooks-api/#use-select)
*/
function useSelect<OptionValue, Multiple extends boolean = false>(
props: UseSelectParameters<OptionValue, Multiple>,
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useSlider/useSlider.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,11 +190,11 @@ function doesSupportTouchActionNone() {
*
* Demos:
*
* - [Slider](https://mui.com/base-ui/react-slider/#hook)
* - [Slider](https://next.mui.com/base-ui/react-slider/#hook)
*
* API:
*
* - [useSlider API](https://mui.com/base-ui/react-slider/hooks-api/#use-slider)
* - [useSlider API](https://next.mui.com/base-ui/react-slider/hooks-api/#use-slider)
*/
export function useSlider(parameters: UseSliderParameters): UseSliderReturnValue {
const {
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useSnackbar/useSnackbar.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@ import { EventHandlers } from '../utils/types';
*
* Demos:
*
* - [Snackbar](https://mui.com/base-ui/react-snackbar/#hook)
* - [Snackbar](https://next.mui.com/base-ui/react-snackbar/#hook)
*
* API:
*
* - [useSnackbar API](https://mui.com/base-ui/react-snackbar/hooks-api/#use-snackbar)
* - [useSnackbar API](https://next.mui.com/base-ui/react-snackbar/hooks-api/#use-snackbar)
*/
export function useSnackbar(parameters: UseSnackbarParameters = {}): UseSnackbarReturnValue {
const {
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useSwitch/useSwitch.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@ import { UseSwitchParameters, UseSwitchReturnValue } from './useSwitch.types';
*
* Demos:
*
* - [Switch](https://mui.com/base-ui/react-switch/#hook)
* - [Switch](https://next.mui.com/base-ui/react-switch/#hook)
*
* API:
*
* - [useSwitch API](https://mui.com/base-ui/react-switch/hooks-api/#use-switch)
* - [useSwitch API](https://next.mui.com/base-ui/react-switch/hooks-api/#use-switch)
*/
export function useSwitch(props: UseSwitchParameters): UseSwitchReturnValue {
const {
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useTab/useTab.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,11 @@ function tabValueGenerator(otherTabValues: Set<string | number>) {
*
* Demos:
*
* - [Tabs](https://mui.com/base-ui/react-tabs/#hooks)
* - [Tabs](https://next.mui.com/base-ui/react-tabs/#hooks)
*
* API:
*
* - [useTab API](https://mui.com/base-ui/react-tabs/hooks-api/#use-tab)
* - [useTab API](https://next.mui.com/base-ui/react-tabs/hooks-api/#use-tab)
*/
function useTab(parameters: UseTabParameters): UseTabReturnValue {
const { value: valueParam, rootRef: externalRef, disabled = false, id: idParam } = parameters;
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useTabPanel/useTabPanel.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@ function tabPanelValueGenerator(otherTabPanelValues: Set<string | number>) {
*
* Demos:
*
* - [Tabs](https://mui.com/base-ui/react-tabs/#hooks)
* - [Tabs](https://next.mui.com/base-ui/react-tabs/#hooks)
*
* API:
*
* - [useTabPanel API](https://mui.com/base-ui/react-tabs/hooks-api/#use-tab-panel)
* - [useTabPanel API](https://next.mui.com/base-ui/react-tabs/hooks-api/#use-tab-panel)
*/
function useTabPanel(parameters: UseTabPanelParameters): UseTabPanelReturnValue {
const { value: valueParam, id: idParam, rootRef: externalRef } = parameters;
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useTabs/useTabs.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@ type IdLookupFunction = (id: string | number) => string | undefined;
*
* Demos:
*
* - [Tabs](https://mui.com/base-ui/react-tabs/#hooks)
* - [Tabs](https://next.mui.com/base-ui/react-tabs/#hooks)
*
* API:
*
* - [useTabs API](https://mui.com/base-ui/react-tabs/hooks-api/#use-tabs)
* - [useTabs API](https://next.mui.com/base-ui/react-tabs/hooks-api/#use-tabs)
*/
function useTabs(parameters: UseTabsParameters): UseTabsReturnValue {
const {
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useTabsList/useTabsList.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@ import { tabsListReducer } from './tabsListReducer';
*
* Demos:
*
* - [Tabs](https://mui.com/base-ui/react-tabs/#hooks)
* - [Tabs](https://next.mui.com/base-ui/react-tabs/#hooks)
*
* API:
*
* - [useTabsList API](https://mui.com/base-ui/react-tabs/hooks-api/#use-tabs-list)
* - [useTabsList API](https://next.mui.com/base-ui/react-tabs/hooks-api/#use-tabs-list)
*/
function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue {
const { rootRef: externalRef } = parameters;
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-base/src/useTransition/useTransitionStateManager.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,11 @@ export type UseTransitionStateManagerReturnValue = {
*
* Demos:
*
* - [Transitions](https://mui.com/base-ui/react-transitions/#hooks)
* - [Transitions](https://next.mui.com/base-ui/react-transitions/#hooks)
*
* API:
*
* - [useTransitionStateManager API](https://mui.com/base-ui/react-transitions/hooks-api/#use-transition-state-manager)
* - [useTransitionStateManager API](https://next.mui.com/base-ui/react-transitions/hooks-api/#use-transition-state-manager)
*/
export function useTransitionStateManager(): UseTransitionStateManagerReturnValue {
const transitionContext = React.useContext(TransitionContext);
Expand Down
Loading
Loading