Docs: use markdown headings instead of links for API declarations #33381

juanmaguitar · 2021-07-13T07:48:00Z

Description

As per #33361 this PR generates proper headings with Symbol names (method names, selectors names, actions names, ...)

How has this been tested?

Locally, by testing the output of commands such as

npx docgen packages/core-data/src/selectors.js --output data-core-dummy.md && cat data-core-dummy.md

Types of changes

Change in the Tool used to generated Documentation (API documentation markdown from JSDOC code comments)

Checklist:

My code is tested.
My code follows the WordPress code style.
My code follows the accessibility standards.
I've tested my changes with keyboard and screen readers.
My code has proper inline documentation.
I've included developer documentation if appropriate.
I've updated all React Native files affected by any refactorings/renamings in this PR (please manually search all *.native.js files for terms that need renaming or removal).

juanmaguitar · 2021-07-13T08:10:26Z

BTW I couldn't find a way to test LOCALLY the final HTML of the docs (like in https://developer.wordpress.org/block-editor/ ) from the markdown files.

Is there any way to generate the final HTML (the one that will be served from https://developer.wordpress.org for example) in the development environment from the markdown files to test changes like the ones in this PR?

oandregal · 2021-07-13T10:14:27Z

👋 @juanmaguitar you may want to do two things for this to be ready:

rebase from trunk (I've just landed a related PR Fix API docs for data reference guides #33384 )
execute npm run docs:build to update all the auto-generated documentation for packages and reference guides

Is there any way to generate the final HTML (the one that will be served from https://developer.wordpress.org for example) in the development environment from the markdown files to test changes like the ones in this PR?

You'd need to replicate a meta environment. I don't know how to do that, but the above command is enough to update the affected markdown files in this repo.

juanmaguitar · 2021-07-13T13:39:22Z

Thanks for the response @nosolosw

you may want to do two things for this to be ready:

rebase from trunk (I've just landed a related PR Fix API docs for data reference guides Fix API docs for data reference guides #33384 )

execute npm run docs:build to update all the auto-generated documentation for packages and reference guides

both things done 👍

juanmaguitar · 2021-07-13T13:44:18Z

BTW I'm not sure I added so many people as reviewers. If I did, it wasn't on purpose.

@nosolosw is this some automatic action? shall I remove these reviewers added?

oandregal · 2021-07-13T14:17:09Z

is this some automatic action? shall I remove these reviewers added?

Yeah, it's automatic. It's fine. Those are people that opted-in to become a reviewer for particular code paths using the codeowners feature (see this file in our repo).

oandregal · 2021-07-13T14:21:19Z

@juanmaguitar I see that the CI actions report some failing tests: packages/docgen/test/formatter-markdown.js. They need to be updated to account for the changes here as well. You can run the docgen tests locally by using the command npm run test-unit -- packages/docgen/.

juanmaguitar · 2021-07-13T15:11:08Z

I see that the CI actions report some failing tests: packages/docgen/test/formatter-markdown.js. They need to be updated to account for the changes here as well. You can run the docgen tests locally by using the command npm run test-unit -- packages/docgen/.

Thanks for the explanation @nosolosw
Tests updated to reflect changes in the code 👍

oandregal

Thanks for the contribution, @juanmaguitar ! I'm going to let the tests end and tomorrow will merge.

For context: once it's merged in trunk, the block editor handbook typically takes 15 to 30 minutes to be updated with the new contents.

oandregal · 2021-07-13T15:34:40Z

Juanma, I've also updated the title of the PR and assigned it some labels, as that's used in the changelog of the releases: the more informative the PR titles are the more informative the changelog for consumers.

juanmaguitar · 2021-07-13T15:40:14Z

I'm going to let the tests end and tomorrow will merge.

I've also updated the title of the PR and assigned it some labels, as that's used in the changelog of the releases: the more informative the PR titles are the more informative the changelog for consumers.

Awesome. Thanks! 🙌

oandregal · 2021-07-14T08:57:04Z

For reference, this is the before/after in a couple of pages in the block editor:

WordPress Core Data

Before	After

a11y package

Before	After

…3381)

* Fix API docs generation (#33384) * Docs: use markdown headings instead of links for API declarations (#33381) * Docs: Run Prettier after updating API in documentation (#33498) (cherry picked from commit 626f233) * Use tabs instead of spaces in block transform doc example (#33549) (cherry picked from commit 8afca1e) * Fix metabox reordering (#30617). * Block editor: don't render layout and duotone styles in between blocks (#32083) * Widgets: Allow HTML tags in description (#33814) * Widgets: Allow HTML tags in description * Use `dangerouslySetInnerHTML` Avoid `<div />` inside the `<p />` tag * Describe by dangerouslySetInnerHTML is used * Use safeHTML * Update comment * Editor: Set 'hide_empty' for the most used terms query (#33457) Don't include terms that aren't assigned to any posts as "most used" terms. * Update widget editor help links to point to the new support article (#33482) * If select-all fires in .editor-post-title__input, end the process.. (#33621) * Writing flow: select all: remove early return for post title (#33699) * Call onChangeSectionExpanded conditionally (#33618) * FontSizePicker: Use number values when the initial value is a number (#33679) * FontSizePicker: Don't use units if the value is a number * Add unit tests * Disable units when we have number values * Fix justification for button block when selected (#33739) * Remove margin setting, auto right conflict with justify buttons * Per review, add little margin back * Add error boundaries to widget screens (#33771) * Add error boundary to edit widgets screen * Add error boundary to customize widgets * Refactor sidebar controls provider to application level so that its state is not lost when re-initializing * Revert "Refactor sidebar controls provider to application level so that its state is not lost when re-initializing" This reverts commit 7d607ff. * Remove rebootability from customize widgets * Remove debug code * Fix insertion point in Widgets editors (#33802) * Default batch processor: Respect the batch endpoint's maxItems (#34280) This updates the default batch processor to make multiple batch requests if the number of requests to process exceeds the number of requests that the batch endpoint can handle. We determine the number of requests that the batch endpoint can handle by making a preflight OPTIONS request to /batch/v1. By default it is 25 requests. See https://make.wordpress.org/core/2020/11/20/rest-api-batch-framework-in-wordpress-5-6/. * Fix button block focus trap after a URL has been added (#34314) * Rework button block link UI to match RichText format implementation * Refine some more, determine visibility by selection and url state * Add e2e test * Also focus rich text when unlinking using a keyboard shortcut * Text for dropdown fields within legacy widgets in the Customizer is off centered (#34076) * Fix ESLint errors reported * Regenerate autogenerated docs * Update the `INSERTER_SEARCH_SELECTOR` path. This is a partial cherry pick of 2356b2d in order to fix the performance tests. Co-authored-by: André <nosolosw@users.noreply.github.com> Co-authored-by: JuanMa <juanma.garrido@gmail.com> Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl> Co-authored-by: Jeff Bowen <jblz@users.noreply.github.com> Co-authored-by: Bruno Ribarić <43731400+ribaricplusplus@users.noreply.github.com> Co-authored-by: Ella van Durpe <4710635+ellatrix@users.noreply.github.com> Co-authored-by: Petter Walbø Johnsgård <petter@dekode.no> Co-authored-by: George Mamadashvili <georgemamadashvili@gmail.com> Co-authored-by: Daniel Richards <daniel.richards@automattic.com> Co-authored-by: Hiroshi Urabe <mail@torounit.com> Co-authored-by: Kai Hao <kevin830726@gmail.com> Co-authored-by: Marcus Kazmierczak <marcus@mkaz.com> Co-authored-by: Robert Anderson <robert@noisysocks.com> Co-authored-by: Anton Vlasenko <43744263+anton-vlasenko@users.noreply.github.com>

symbol name as proper heading level 2

284c040

juanmaguitar requested a review from oandregal as a code owner July 13, 2021 07:48

juanmaguitar changed the title ~~Symbol name as proper heading level 2~~ Docs Tools: Symbol name as proper heading level 2 Jul 13, 2021

juanmaguitar added 3 commits July 13, 2021 12:45

Merge branch 'WordPress:trunk' into docgen-fix-heading-symbol

10b97d2

Merge branch 'WordPress:trunk' into docgen-fix-heading-symbol

32245fd

added generated md w/ proper headings for symbol names

511339b

juanmaguitar requested review from adamsilverstein, ajitbohra, cameronvoell, chrisvanpatten, dmsnell, ellatrix, guarani, gziolo, nerrad, ntwb and swissspidy as code owners July 13, 2021 13:34

modified test to include change in formatter

fb2f09f

oandregal approved these changes Jul 13, 2021

View reviewed changes

oandregal changed the title ~~Docs Tools: Symbol name as proper heading level 2~~ Docs: use markdown headings instead of links for API declarations Jul 13, 2021

oandregal added the [Type] Developer Documentation Documentation for developers label Jul 13, 2021

oandregal added the developer-docs label Jul 13, 2021

removed coverage folder

8d6272b

oandregal merged commit 5b32e25 into WordPress:trunk Jul 14, 2021

github-actions bot added this to the Gutenberg 11.1 milestone Jul 14, 2021

juanmaguitar deleted the docgen-fix-heading-symbol branch July 14, 2021 08:38

priethor mentioned this pull request Jul 19, 2021

Automate grouping of release Changelog PRs by feature #33229

Merged

12 tasks

desrosj pushed a commit that referenced this pull request Aug 30, 2021

Docs: use markdown headings instead of links for API declarations (#3…

728dcd7

…3381)

desrosj mentioned this pull request Aug 30, 2021

WordPress 5.8.1 backports #34393

Merged

7 tasks

snyk-bot mentioned this pull request Sep 11, 2022

[Snyk] Upgrade react-native from 0.66.2 to 0.69.4 captainbarber99/gutenberg#5

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: use markdown headings instead of links for API declarations #33381

Docs: use markdown headings instead of links for API declarations #33381

juanmaguitar commented Jul 13, 2021 •

edited by oandregal

juanmaguitar commented Jul 13, 2021 •

edited

oandregal commented Jul 13, 2021

juanmaguitar commented Jul 13, 2021 •

edited

juanmaguitar commented Jul 13, 2021

oandregal commented Jul 13, 2021

oandregal commented Jul 13, 2021 •

edited

juanmaguitar commented Jul 13, 2021

oandregal left a comment

oandregal commented Jul 13, 2021

juanmaguitar commented Jul 13, 2021

oandregal commented Jul 14, 2021

Docs: use markdown headings instead of links for API declarations #33381

Docs: use markdown headings instead of links for API declarations #33381

Conversation

juanmaguitar commented Jul 13, 2021 • edited by oandregal

Description

How has this been tested?

Types of changes

Checklist:

juanmaguitar commented Jul 13, 2021 • edited

oandregal commented Jul 13, 2021

juanmaguitar commented Jul 13, 2021 • edited

juanmaguitar commented Jul 13, 2021

oandregal commented Jul 13, 2021

oandregal commented Jul 13, 2021 • edited

juanmaguitar commented Jul 13, 2021

oandregal left a comment

Choose a reason for hiding this comment

oandregal commented Jul 13, 2021

juanmaguitar commented Jul 13, 2021

oandregal commented Jul 14, 2021

juanmaguitar commented Jul 13, 2021 •

edited by oandregal

juanmaguitar commented Jul 13, 2021 •

edited

juanmaguitar commented Jul 13, 2021 •

edited

oandregal commented Jul 13, 2021 •

edited