documentation-developer icon indicating copy to clipboard operation
documentation-developer copied to clipboard

Published 20 hours ago • verified publisher icon ibexa

Code samples usage

Open adriendupuis opened this issue 1 year ago • 2 comments

Question Answer
JIRA Ticket N/A
Versions master, 4.6
Edition N/A

Tool to search and preview code samples usage. It outputs a list of Markdown code blocks using include_file, each followed by a preview of its rendering. For examples:

  • php tools/code_samples/code_samples_usage.php code_samples/api/product_catalog/src/Command/AttributeCommand.php code_samples/api/product_catalog/src/Command/ProductCommand.php lists usages of the two files passed as arguments (argument count is unlimited).
  • php tools/code_samples/code_samples_usage.php lists every include_file usage.

⫸ indicates a highlighted line (hl_lines).

The tool is used by a GitHub action for CI on pull request. It compares the usage of modified code_samples/ files between the target branch and the current branch. If there is changes in code_samples/, this action posts its report as a comment on the PR. It deletes its previous comment if it exists. (It could have edit and update the previous one but an old comment can become hidden by default and stay hidden even if updated.) Because of GitHub limitation, the comment can be hard to read. A colorized version is available as HTML file in a downloadable archive (due to artefact limitation, it can't be seen online or downloaded unzipped).

See the "code_samples/ change report" comment below for an example with two bonus modification.

Bonus:

Two PHP files are modified for demo, they had too long __construct lines and new lines are added:

  • code_samples/api/product_catalog/src/Command/AttributeCommand.php
  • code_samples/api/product_catalog/src/Command/ProductCommand.php

A report comment helps to check side effects on their usage.

The page using them doesn't change:

  • https://doc.ibexa.co/en/latest/pim/product_api/
  • https://ez-systems-developer-documentation--2438.com.readthedocs.build/en/2438/pim/product_api/

docs/pim/price_api.md has been modified. As the PHP code doesn't change, there is nothing about it in the report comment. Locally, the changes can be checked with php tools/code_samples/code_samples_usage.php code_samples/api/product_catalog/src/Command/ProductPriceCommand.php which could be simpler than running mkdocs server.

Remove duplicated blank lines before // ...:

  • https://doc.ibexa.co/en/latest/pim/price_api/#prices
  • https://ez-systems-developer-documentation--2438.com.readthedocs.build/en/2438/pim/price_api/#prices

Cases checks

  • [x] There is no change in code_samples/
  • [x] A code_samples/ file have been modified and its inclusions have different outputs than previously
  • [x] A code_samples/ file have been modified but it makes no difference in its inclusions
  • [x] A file as been renamed in code_samples/ but not in its inclusion
  • [x] A file as been renamed in code_samples/ and in its inclusion
  • [x] A file as been removed from code_samples/ but it's still included

Checklist

  • [ ] Text renders correctly
  • [ ] Text has been checked with vale
  • [ ] Description metadata is up to date
  • [ ] Redirects cover removed/moved pages
  • [ ] Code samples are working
  • [ ] PHP code samples have been fixed with PHP CS fixer
  • [ ] Added link to this PR in relevant JIRA ticket or code PR

adriendupuis avatar Jul 15 '24 15:07 adriendupuis

Another test in #2485

adriendupuis avatar Aug 30 '24 13:08 adriendupuis

code_samples/ change report

Before (on target branch)After (in current PR)

code_samples/api/product_catalog/src/Command/AttributeCommand.php

docs/pim/product_api.md@147:``` php

code_samples/api/product_catalog/src/Command/AttributeCommand.php

docs/pim/product_api.md@147:``` php
docs/pim/product_api.md@148:[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 64, 65) =]]
docs/pim/product_api.md@149:[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 85, 90) =]]
docs/pim/product_api.md@148:[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 71, 72) =]]
docs/pim/product_api.md@149:[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 92, 97) =]]
docs/pim/product_api.md@150:```

001⫶        $attributeGroup = $this->attributeGroupService->getAttributeGroup('dimensions');
002⫶
003⫶        $attributeGroups = $this->attributeGroupService->findAttributeGroups();
004⫶
005⫶        foreach ($attributeGroups as $attributeGroup) {
006⫶            $output->writeln('Attribute group ' . $attributeGroup->getIdentifier() . ' with name ' . $attributeGroup->getName());
007⫶        }

docs/pim/product_api.md@155:``` php
docs/pim/product_api.md@150:```

001⫶        $attributeGroup = $this->attributeGroupService->getAttributeGroup('dimensions');
002⫶
003⫶        $attributeGroups = $this->attributeGroupService->findAttributeGroups();
004⫶
005⫶        foreach ($attributeGroups as $attributeGroup) {
006⫶            $output->writeln('Attribute group ' . $attributeGroup->getIdentifier() . ' with name ' . $attributeGroup->getName());
007⫶        }

docs/pim/product_api.md@155:``` php
docs/pim/product_api.md@156:[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 59, 63) =]]
docs/pim/product_api.md@156:[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 66, 70) =]]
docs/pim/product_api.md@157:```

001⫶        $attributeGroupCreateStruct = $this->localAttributeGroupService->newAttributeGroupCreateStruct('dimensions');
002⫶        $attributeGroupCreateStruct->setNames(['eng-GB' => 'Size']);
003⫶
004⫶        $this->localAttributeGroupService->createAttributeGroup($attributeGroupCreateStruct);

docs/pim/product_api.md@162:``` php
docs/pim/product_api.md@157:```

001⫶        $attributeGroupCreateStruct = $this->localAttributeGroupService->newAttributeGroupCreateStruct('dimensions');
002⫶        $attributeGroupCreateStruct->setNames(['eng-GB' => 'Size']);
003⫶
004⫶        $this->localAttributeGroupService->createAttributeGroup($attributeGroupCreateStruct);

docs/pim/product_api.md@162:``` php
docs/pim/product_api.md@163:[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 71, 73) =]]
docs/pim/product_api.md@163:[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 78, 80) =]]
docs/pim/product_api.md@164:```

001⫶        $attribute = $this->attributeDefinitionService->getAttributeDefinition('length');
002⫶        $output->writeln($attribute->getName());

docs/pim/product_api.md@169:``` php
docs/pim/product_api.md@164:```

001⫶        $attribute = $this->attributeDefinitionService->getAttributeDefinition('length');
002⫶        $output->writeln($attribute->getName());

docs/pim/product_api.md@169:``` php
docs/pim/product_api.md@170:[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 76, 82) =]]
docs/pim/product_api.md@170:[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 83, 89) =]]
docs/pim/product_api.md@171:```

001⫶        $attributeCreateStruct = $this->localAttributeDefinitionService->newAttributeDefinitionCreateStruct('size');
002⫶        $attributeCreateStruct->setType($attributeType);
003⫶        $attributeCreateStruct->setName('eng-GB', 'Size');
004⫶        $attributeCreateStruct->setGroup($attributeGroup);
005⫶
006⫶        $this->localAttributeDefinitionService->createAttributeDefinition($attributeCreateStruct);


code_samples/api/product_catalog/src/Command/ProductCommand.php

docs/pim/product_api.md@22:``` php
docs/pim/product_api.md@171:```

001⫶        $attributeCreateStruct = $this->localAttributeDefinitionService->newAttributeDefinitionCreateStruct('size');
002⫶        $attributeCreateStruct->setType($attributeType);
003⫶        $attributeCreateStruct->setName('eng-GB', 'Size');
004⫶        $attributeCreateStruct->setGroup($attributeGroup);
005⫶
006⫶        $this->localAttributeDefinitionService->createAttributeDefinition($attributeCreateStruct);


code_samples/api/product_catalog/src/Command/ProductCommand.php

docs/pim/product_api.md@22:``` php
docs/pim/product_api.md@23:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 62, 65) =]]
docs/pim/product_api.md@23:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 68, 71) =]]
docs/pim/product_api.md@24:```

001⫶        $product = $this->productService->getProduct($productCode);
002⫶
003⫶        $output->writeln('Product with code ' . $product->getCode() . ' is ' . $product->getName());

docs/pim/product_api.md@29:``` php
docs/pim/product_api.md@24:```

001⫶        $product = $this->productService->getProduct($productCode);
002⫶
003⫶        $output->writeln('Product with code ' . $product->getCode() . ' is ' . $product->getName());

docs/pim/product_api.md@29:``` php
docs/pim/product_api.md@30:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 66, 76) =]]
docs/pim/product_api.md@30:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 72, 82) =]]
docs/pim/product_api.md@31:```

001⫶        $criteria = new Criterion\ProductType([$productType]);
002⫶        $sortClauses = [new SortClause\ProductName(ProductQuery::SORT_ASC)];
003⫶
004⫶        $productQuery = new ProductQuery(null, $criteria, $sortClauses);
005⫶
006⫶        $products = $this->productService->findProducts($productQuery);
007⫶
008⫶        foreach ($products as $product) {
009⫶            $output->writeln($product->getName() . ' of type ' . $product->getProductType()->getName());
010⫶        }

docs/pim/product_api.md@37:``` php
docs/pim/product_api.md@31:```

001⫶        $criteria = new Criterion\ProductType([$productType]);
002⫶        $sortClauses = [new SortClause\ProductName(ProductQuery::SORT_ASC)];
003⫶
004⫶        $productQuery = new ProductQuery(null, $criteria, $sortClauses);
005⫶
006⫶        $products = $this->productService->findProducts($productQuery);
007⫶
008⫶        foreach ($products as $product) {
009⫶            $output->writeln($product->getName() . ' of type ' . $product->getProductType()->getName());
010⫶        }

docs/pim/product_api.md@37:``` php
docs/pim/product_api.md@38:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 87, 91) =]]
docs/pim/product_api.md@38:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 93, 97) =]]
docs/pim/product_api.md@39:```

001⫶        $productUpdateStruct = $this->localProductService->newProductUpdateStruct($product);
002⫶        $productUpdateStruct->setCode('NEWMODIFIEDPRODUCT');
003⫶
004⫶        $this->localProductService->updateProduct($productUpdateStruct);

docs/pim/product_api.md@45:``` php
docs/pim/product_api.md@39:```

001⫶        $productUpdateStruct = $this->localProductService->newProductUpdateStruct($product);
002⫶        $productUpdateStruct->setCode('NEWMODIFIEDPRODUCT');
003⫶
004⫶        $this->localProductService->updateProduct($productUpdateStruct);

docs/pim/product_api.md@45:``` php
docs/pim/product_api.md@46:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 77, 84) =]]
docs/pim/product_api.md@46:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 83, 90) =]]
docs/pim/product_api.md@47:```

001⫶        $productType = $this->productTypeService->getProductType($productType);
002⫶
003⫶        $createStruct = $this->localProductService->newProductCreateStruct($productType, 'eng-GB');
004⫶        $createStruct->setCode('NEWPRODUCT');
005⫶        $createStruct->setField('name', 'New Product');
006⫶
007⫶        $this->localProductService->createProduct($createStruct);

docs/pim/product_api.md@51:``` php
docs/pim/product_api.md@47:```

001⫶        $productType = $this->productTypeService->getProductType($productType);
002⫶
003⫶        $createStruct = $this->localProductService->newProductCreateStruct($productType, 'eng-GB');
004⫶        $createStruct->setCode('NEWPRODUCT');
005⫶        $createStruct->setField('name', 'New Product');
006⫶
007⫶        $this->localProductService->createProduct($createStruct);

docs/pim/product_api.md@51:``` php
docs/pim/product_api.md@52:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 114, 115) =]]
docs/pim/product_api.md@52:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 120, 121) =]]
docs/pim/product_api.md@53:```

001⫶        $this->localProductService->deleteProduct($product);

docs/pim/product_api.md@127:```php
docs/pim/product_api.md@53:```

001⫶        $this->localProductService->deleteProduct($product);

docs/pim/product_api.md@127:```php
docs/pim/product_api.md@128:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 98, 103) =]]        }
docs/pim/product_api.md@128:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 104, 109) =]]        }
docs/pim/product_api.md@129:```

001⫶        if ($this->productAvailabilityService->hasAvailability($product)) {
002⫶            $availability = $this->productAvailabilityService->getAvailability($product);
003⫶
004⫶            $output->write($availability->isAvailable() ? 'Available' : 'Unavailable');
005⫶            $output->writeln(' with stock ' . $availability->getStock());
006⫶        }

docs/pim/product_api.md@135:``` php
docs/pim/product_api.md@129:```

001⫶        if ($this->productAvailabilityService->hasAvailability($product)) {
002⫶            $availability = $this->productAvailabilityService->getAvailability($product);
003⫶
004⫶            $output->write($availability->isAvailable() ? 'Available' : 'Unavailable');
005⫶            $output->writeln(' with stock ' . $availability->getStock());
006⫶        }

docs/pim/product_api.md@135:``` php
docs/pim/product_api.md@136:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 106, 109) =]]
docs/pim/product_api.md@136:[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 112, 115) =]]
docs/pim/product_api.md@137:```

001⫶            $productAvailabilityUpdateStruct = new ProductAvailabilityUpdateStruct($product, true, false, 80);
002⫶
003⫶            $this->productAvailabilityService->updateProductAvailability($productAvailabilityUpdateStruct);

docs/pim/product_api.md@137:```

001⫶            $productAvailabilityUpdateStruct = new ProductAvailabilityUpdateStruct($product, true, false, 80);
002⫶
003⫶            $this->productAvailabilityService->updateProductAvailability($productAvailabilityUpdateStruct);

Download colorized diff

github-actions[bot] avatar Sep 05 '24 08:09 github-actions[bot]