[Doc] buildpack ref docs #2508

jcalcaben · 2020-06-24T15:29:54Z

Description

This PR updates the JSDocs in the targets in the Buildpack package.
It also creates a file in devdocs that pulls this information into a reference-style topic.

Related Issue

Closes PWA-703

Acceptance

@zetlen

Verification Stakeholders

@zetlen

Specification

Verification Steps

Navigate to the pwa devdocs directory: cd pwa-devdocs
Start the HTML preview server: yarn develop
Verify files are auto-generated:
- src/_includes/auto-generated/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.md
- src/_includes/auto-generated/pwa-buildpack/lib/BuildBus/declare-base.md
- src/_includes/auto-generated/pwa-buildpack/lib/BuildBus/BuildBus.md
- src/_includes/auto-generated/pwa-buildpack/lib/BuildBus/TargetProvider.md
- src/_includes/auto-generated/pwa-buildpack/lib/BuildBus/Target.md
- src/_includes/auto-generated/pwa-buildpack/lib/Utilities/getEnvVarDefinitions.js
On the devdocs preview site, in the top navigation, click on PWA Buildpack under the Reference API item.
Verify new navigation layout
Verify all the links under the Extension points, Extension framework, Developer utilities, Webpack tools, and Environment configuration sections work.

Screenshots / Screen Captures (if appropriate)

Checklist

I have added tests to cover my changes, if necessary.

I have updated the documentation accordingly, if necessary.

PWAStudioBot · 2020-06-24T15:42:34Z

	Messages
📖	Access a deployed version of this PR here. Make sure to wait for the "pwa-pull-request-deploy" job to complete.
📖	DangerCI Failures related to missing labels/description/linked issues/etc will persist until the next push or next nightly build run (assuming they are fixed).
📖	Associated JIRA tickets: PWA-703.

Generated by 🚫 dangerJS against 89a63cd

devops-pwa-codebuild · 2020-06-24T15:53:09Z

Performance Test Results

The following fails have been reported by WebpageTest. These numbers indicates a possible performance issue with the PR which requires further manual testing to validate.

https://pr-2508.pwa-venia.com : LH Performance Expected 0.85 Actual 0.34, LH Accessibility Expected 1 Actual 0.97, LH Best Practices Expected 1 Actual 0.92, WPT Cache Expected 90 Actual 39.333333333333
https://pr-2508.pwa-venia.com/venia-tops.html : LH Performance Expected 0.75 Actual 0.34, LH Best Practices Expected 1 Actual 0.92
https://pr-2508.pwa-venia.com/valeria-two-layer-tank.html : LH Performance Expected 0.8 Actual 0.39, LH Accessibility Expected 0.9 Actual 0.89, LH Best Practices Expected 1 Actual 0.92, WPT Cache Expected 65 Actual 50

…jimothy/buildpack-ref-docs

zetlen

Partial review for @jcalcaben because I'm taking so long with this process. There's enough here to start a conversation--I'll continue to review this and the other two after submitting.

zetlen · 2020-07-20T18:15:50Z

packages/pwa-buildpack/lib/BuildBus/BuildBus.js

- * for dependencies with Targets to interact with each other.
- *
+ * Manages dependency participation in project builds and tasks.
+ * It connects dependencies with Targets and lets them interact with each other.


Might want to add something like executes their declare and intercept files so they can interact with each other.

packages/pwa-buildpack/lib/BuildBus/BuildBus.js

packages/pwa-buildpack/lib/BuildBus/Target.js

zetlen · 2020-07-22T01:22:12Z

packages/pwa-buildpack/lib/BuildBus/TargetProvider.js

+ * Respond to a request from a [TargetProvider]{@link https://pwastudio.io/pwa-buildpack/reference/buildbus/targetprovider/}
+ * to retrieve a different(external) TargetProvider.
+ * 
+ * When using a TargetProvider disconnected from a


I sort of regret this aside, because I can't think of a single reason you'd use a TargetProvider disconnected from a BuildBus. Maybe this should just say "This callback pattern helps to loosely couple TargetProviders so they are more testable."

packages/pwa-buildpack/lib/BuildBus/TargetProvider.js

zetlen · 2020-07-22T01:33:54Z

packages/pwa-buildpack/lib/BuildBus/declare-base.js

         * Collects requests to intercept and modify individual files from this
-         * dependency. Only files from the currently requesting dependency may
+         * dependency.
+         *
+         * Only files from the currently requesting dependency may
         * be transformed.


What I wrote is no longer accurate. We added an exception for interceptor files in the project itself (e.g. venia-concept) to be able to transform ANY file from ANY dependency. It's only the dependencies (e.g. venia-ui) that are prevented from modifying files from other dependencies (e.g. peregrine).

We did this because a custom interceptor file for the project should be able to do whatever it wants, since it's presumably maintained by the project author who is also in charge of importing dependencies.

Can you help me to put that here?

zetlen · 2020-07-22T01:34:46Z

packages/pwa-buildpack/lib/BuildBus/declare-base.js

@@ -196,3 +179,65 @@ module.exports = targets => {

    targets.declare(builtins);
 };
+


Ohhh, this makes sense. Thanks for this reorg.

Co-authored-by: James Zetlen <jzetlen@adobe.com>

zetlen

Finishing up the first round. Thanks for your patience.

packages/pwa-buildpack/lib/BuildBus/declare-base.js

zetlen · 2020-07-23T22:02:27Z

packages/pwa-buildpack/lib/BuildBus/declare-base.js

+         * Since the storefront developer is in charge of important dependencies, 
+         * the interceptor files in the storefront project itself should be able to
+         * transform ANY file from ANY dependency.
+         * However, interceptor files in the storefront dependencies are prevented


packages/pwa-buildpack/lib/BuildBus/mapHooksToTargets.js

pwa-devdocs/scripts/create-reference-docs/config/buildpack.js

zetlen · 2020-07-23T22:15:25Z

pwa-devdocs/scripts/create-reference-docs/config/buildpack.js

+    {
+        target: 'pwa-buildpack/lib/BuildBus/declare-base.js',
+        type: 'function'
+    },


Does this belong here? The declare-base.js file is what declares Buildpack targets, so we wrote the doc blocks in that file. But the targets themselves are in a different category of thing, which should be documented in a separate "Targets" section, right?

I can't add another level of nesting to the navigation, so they will all need to go under "Extensibility"

pwa-devdocs/src/_data/buildpack-api.yml

zetlen · 2020-07-23T22:17:33Z

pwa-devdocs/src/_data/buildpack-api.yml

+    - label: BuildBus
+      url: /pwa-buildpack/reference/buildbus/
+      entries:
+        - label: Extensibility Targets
+          url: /pwa-buildpack/reference/buildbus/targets/


I know that I called the directory BuildBus in source code, but I think in documentation, the top-level item should be called "Extensibility" and there should be an additional entry below, called "BuildBus".

zetlen · 2020-07-23T22:17:52Z

pwa-devdocs/src/_data/buildpack-api.yml

+    - label: ModuleTransformConfig
+      url: /pwa-buildpack/reference/moduletransformconfig/
+


This belongs under Extensibility

Co-authored-by: James Zetlen <jzetlen@adobe.com>

* docs: elaborate on envVarDefinitions API * Apply suggestions from code review Co-authored-by: James Zetlen <jzetlen@adobe.com> * Update pwa-devdocs/src/pwa-buildpack/reference/environment-variables/index.md Co-authored-by: James Calcaben <jcalcaben@users.noreply.github.com> * Update pwa-devdocs/src/pwa-buildpack/reference/environment-variables/index.md Co-authored-by: James Calcaben <jcalcaben@users.noreply.github.com> * docs: elaborate on envVarDefinitions API Co-authored-by: James Calcaben <jcalcaben@users.noreply.github.com>

* bluh * docs: reorg buildpack ref path

packages/pwa-buildpack/lib/BuildBus/Target.js

zetlen

LGTM 👍

dpatil-magento · 2020-08-04T16:59:24Z

Verification steps look good.

jcalcaben added 4 commits June 17, 2020 13:48

Add buildpack configuration file to reference doc generator script

3ddfc38

Add topic for buildpack target ref docs

db283be

Add module transform config ref docs and add to nav

f7fe225

Revise js docs

d840b65

jcalcaben added pkg:pwa-devdocs documentation This pertains to documentation. version: Minor This changeset includes functionality added in a backwards compatible manner. docs documentation labels Jun 24, 2020

m2-community-project bot added this to Ready for Review in Pull Request Progress Jun 24, 2020

PWAStudioBot added the pkg:pwa-buildpack label Jun 24, 2020

jcalcaben and others added 8 commits June 24, 2020 11:55

Add other reference topics

5f9c304

Add initial files for the new ref topics

a564368

Revise jsdocs for BuildBus and TargetProvider

c54808c

Revise JSDocs for the mapHooksToTarget file

8d899f8

Revise JSDocs on the Target file

0933bcb

Revise JSDocs in TargetProvider

1cbeadf

Minor fixes

67f3d8e

Merge branch 'develop' of https://github.com/magento/pwa-studio into …

b8b37a1

…jimothy/buildpack-ref-docs

zetlen reviewed Jul 23, 2020

View reviewed changes

m2-community-project bot assigned zetlen Jul 23, 2020

m2-community-project bot moved this from Ready for Review to Review in Progress in Pull Request Progress Jul 23, 2020

m2-community-project bot added the Progress: review label Jul 23, 2020

Apply suggestions from code review

efad96c

Co-authored-by: James Zetlen <jzetlen@adobe.com>

m2-community-project bot assigned jcalcaben Jul 23, 2020

Revise JSDoc based on feedback

87cf924

zetlen suggested changes Jul 23, 2020

View reviewed changes

zetlen mentioned this pull request Jul 24, 2020

[Doc] Suggested additions to buildpack ref docs #2575

Merged

1 task

Apply suggestions from code review

3835392

Co-authored-by: James Zetlen <jzetlen@adobe.com>

James Zetlen and others added 3 commits July 24, 2020 12:58

Make changes based on feedback and removed 'in develop' notice

66388a1

Revise new environment variables topic

49da080

jcalcaben requested a review from zetlen July 24, 2020 18:57

zetlen mentioned this pull request Jul 24, 2020

[DOC] Suggested reorg of Buildpack reference doc content #2579

Merged

1 task

James Zetlen and others added 2 commits July 27, 2020 11:08

[DOC] Suggested reorg of Buildpack reference doc content (#2579)

1b517cb

* bluh * docs: reorg buildpack ref path

Fix links in doc blocks

9cf20fe

zetlen previously approved these changes Jul 27, 2020

View reviewed changes

packages/pwa-buildpack/lib/BuildBus/Target.js Outdated Show resolved Hide resolved

doc: fix typo in Target docblock

7049489

zetlen dismissed their stale review via 7049489 July 27, 2020 21:06

James Zetlen and others added 3 commits July 27, 2020 16:06

Merge branch 'develop' into jimothy/buildpack-ref-docs

14eed67

docs: revise buildpack devdocs (#2598)

c649817

Fix links

d40f3e3

jcalcaben requested a review from zetlen August 3, 2020 19:55

Merge branch 'develop' into jimothy/buildpack-ref-docs

29ce84a

zetlen approved these changes Aug 3, 2020

View reviewed changes

Merge branch 'develop' into jimothy/buildpack-ref-docs

89a63cd

m2-community-project bot moved this from Review in Progress to Reviewer Approved in Pull Request Progress Aug 4, 2020

m2-community-project bot added Progress: approved and removed Progress: review labels Aug 4, 2020

dpatil-magento merged commit 8fc82a3 into develop Aug 4, 2020

dpatil-magento deleted the jimothy/buildpack-ref-docs branch August 4, 2020 16:59

m2-community-project bot moved this from Reviewer Approved to Done in Pull Request Progress Aug 4, 2020

m2-community-project bot removed the Progress: approved label Aug 4, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Doc] buildpack ref docs #2508

[Doc] buildpack ref docs #2508

jcalcaben commented Jun 24, 2020 •

edited

PWAStudioBot commented Jun 24, 2020 •

edited

devops-pwa-codebuild commented Jun 24, 2020 •

edited

zetlen left a comment

zetlen Jul 20, 2020

zetlen Jul 22, 2020

zetlen Jul 22, 2020

zetlen Jul 22, 2020

zetlen left a comment

zetlen Jul 23, 2020

zetlen Jul 23, 2020

jcalcaben Jul 24, 2020

zetlen Jul 23, 2020

zetlen Jul 23, 2020

zetlen left a comment

dpatil-magento commented Aug 4, 2020

		@@ -196,3 +179,65 @@ module.exports = targets => {

		targets.declare(builtins);
		};

		- label: ModuleTransformConfig
		url: /pwa-buildpack/reference/moduletransformconfig/

[Doc] buildpack ref docs #2508

[Doc] buildpack ref docs #2508

Conversation

jcalcaben commented Jun 24, 2020 • edited

Description

Related Issue

Acceptance

Verification Stakeholders

Specification

Verification Steps

Screenshots / Screen Captures (if appropriate)

Checklist

PWAStudioBot commented Jun 24, 2020 • edited

devops-pwa-codebuild commented Jun 24, 2020 • edited

zetlen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zetlen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zetlen left a comment

Choose a reason for hiding this comment

dpatil-magento commented Aug 4, 2020

jcalcaben commented Jun 24, 2020 •

edited

PWAStudioBot commented Jun 24, 2020 •

edited

devops-pwa-codebuild commented Jun 24, 2020 •

edited