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

Jump to bottom

PHP API Ref external links #2533

Draft
wants to merge 4 commits into
base: master
Choose a base branch
from
Draft

PHP API Ref external links #2533

wants to merge 4 commits into from

Conversation

adriendupuis
Copy link
Contributor

@adriendupuis adriendupuis commented Nov 7, 2024 •
edited
Loading

Question Answer
JIRA Ticket N/A
Versions 4.6+
Edition All

Add an external link to extended parents from Symfony namespace.

In ibexa/core#377, I add the link into the class description. But, because of inheritance, it doesn't fit well when a class inherit this doc in cascade.
For example, BeforeAddRelationEvent reference page has the same "Event emitted before action execution." introduction than BeforeEvent ref page by inheritance. BeforeAddRelationEvent.php doesn't have such doc block. It comes from the extended class doc in BeforeEvent.php. BeforeAddRelationEvent shouldn't pretend being linked directly to Symfony\Contracts\EventDispatcher\Event (my PoV here is debatable). So, here is an other approach.

In 7060ffd I propose to link Symfony namespace to https://github.com/symfony/symfony/

It could be safer to only link Symfony\Contracts namespace but I'm optimist.

symfony/symfony isn't a bundle and seems to be a meta repo concatenating several Symfony bundles. But, it's useful as it's the one using Symfony version.

To target Symfony 5.4 branch should be safe, and it's simpler to maintain than targeting a specific patch tag.

I have tested all the generated links and it works find, no broken link.

$grep = explode(PHP_EOL, trim(`grep "https://github.com/symfony/symfony/blob/5.4/src" -R docs/api/php_api/php_api_reference;`));
foreach ($grep as $grepLine) {
    $parts = explode(':', $grepLine, 2);
    $file = $parts[0];
    preg_match('@https://github.com/symfony/symfony/blob/5.4/src[^"]*@', $parts[1], $matches);
    $url = $matches[0];
    $headers = explode(PHP_EOL, `curl -IsS '$url';`);
    if ('HTTP/2 200' != trim($headers[0])) {
        echo "BROKEN LINK IN $file: $url\n";
    //} else {
    //    echo "OK $file: $url\n";
    }
}

PHP API Reference previews of all the enhanced classes:

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
PHP API Ref: Fix external link CSS
61915b8
@adriendupuis
PHP API Ref: Link Symfony namespace to GitHub
7060ffd
@adriendupuis
Generate PHP API Ref HTML
475ce14
@adriendupuis
Merge branch 'master' into php-api-ref-external-links
9f976f1 
# Conflicts:
#	docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Test-IbexaKernelTestCase.html
#	docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Test-IbexaTestKernel.html
#	docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Test-Repository-SetupFactory-Legacy.html
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@adriendupuis