Skip to content

Commit

Permalink
Get #2584 enhancements
Browse files Browse the repository at this point in the history
  • Loading branch information
adriendupuis committed Dec 20, 2024
1 parent 177c2d8 commit f6f0894
Show file tree
Hide file tree
Showing 15 changed files with 192 additions and 30 deletions.
1 change: 1 addition & 0 deletions tools/php_api_ref/.phpdoc/template/base.html.twig
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
{{ parent() }}

<script>
window.symfonyVersion = '{{ symfony_version }}';
window.addEventListener('keyup', (event) => {
if (event.key === '/') {
event.stopImmediatePropagation();
Expand Down
18 changes: 11 additions & 7 deletions tools/php_api_ref/.phpdoc/template/class.html.twig
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@

{% block content %}
{% include 'components/breadcrumbs.html.twig' %}
{% include 'components/class-title.html.twig' with { symfony_version: symfony_version } %}
{% include('components/element-header.html.twig') %}
{% include 'components/class-title.html.twig' %}
{% include 'components/element-header.html.twig' %}
{% include 'components/constants.html.twig' %}
{% include 'components/properties.html.twig' %}
{% include 'components/methods.html.twig' %}
Expand Down Expand Up @@ -52,12 +52,16 @@
</a>
<nav class="md-nav">
<ul class="md-nav__list">
{% set treated_properties = [] %}
{% for property in properties|sortByVisibility %}
<li class="md-nav__item level-2">
<a href="{{ link(property) }}" title="{{ property.name }}" class="md-nav__link">
{{ property.name }}
</a>
</li>
{% if property.__toString() not in treated_properties %}
<li class="md-nav__item level-2">
<a href="{{ link(property) }}" title="{{ property.name }}" class="md-nav__link">
{{ property.name }}
</a>
</li>
{% set treated_properties = treated_properties|merge([property.__toString()]) %}
{% endif %}
{% endfor %}
</ul>
</nav>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,13 @@
add_edition: true,
} %}
{% block subheader %}
{% if node.isAbstract %}
<div class="content-header__subheader">Abstract</div>
{% endif %}

{% if node.parent %}
<div class="content-header__subheader">
{% if node.parent.__toString starts with '\\Symfony\\' %}
Extends
<a href="{{ 'https://github.com/symfony/symfony/blob/' ~ symfony_version ~ '/src' ~ node.parent|replace({'\\': '/'}) ~ '.php' }}" class="external">
<abbr title="{{ node.parent }}">{{ node.parent.name }}</abbr>
</a>
{% else %}
Extends {{ node.parent|route('class:short') }}
{% endif %}
Extends {{ node.parent|route('class:short') }}
</div>
{% endif %}

Expand Down
29 changes: 18 additions & 11 deletions tools/php_api_ref/.phpdoc/template/components/edition-tag.html.twig
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
{% extends "package-edition-map.twig" %}

{% block content %}
{% set edition_list = [
{# List of displayable editions sorted in inclusion order, each edition includes the previous ones #}
{% set edition_pill_list = [
'experience',
'commerce',
] %}
Expand All @@ -17,15 +18,21 @@
{% endfor %}
{% endif %}

{% if package_edition_map[package] is defined and package_edition_map[package] in edition_list %}
{% set is_supporting = false %}
{% for edition in edition_list %}
{% if edition == package_edition_map[package] %}
{% set is_supporting = true %}
{% endif %}
{% if is_supporting %}
<div class="pill {{ edition }}-pill"></div>
{% endif %}
{% endfor %}
{% if package_edition_map[package] is defined %}
{% if package_edition_map[package] in edition_pill_list %}
{% set is_supporting = false %}
{# display edition pills since minimal edition supporting the package #}
{% for edition in edition_pill_list %}
{% if edition == package_edition_map[package] %}
{% set is_supporting = true %}
{% endif %}
{% if is_supporting %}
<div class="pill {{ edition }}-pill"></div>
{% endif %}
{% endfor %}
{% endif %}
{% else %}
{# if package is not in an edition #}
<div class="pill optional-pill" title="Included in the optional package {{ package }}"></div>
{% endif %}
{% endblock %}
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@
add_edition: true,
} %}
{% block subheader %}
<div class="content-header__subheader">Interface</div>

{% if node.parent is not empty %}
<div class="content-header__subheader">
Extends
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
{% set properties = properties(node)|sortByVisibility %}
{% set explorable_properties = properties(node)|sortByVisibility %}
{% set treated_properties = [] %}

{% if properties is not empty %}
<h2 id="properties">
Expand All @@ -7,7 +9,14 @@
</h2>

{% for property in properties %}
{% include 'components/property.html.twig' %}
{% if property.__toString() not in treated_properties %}
{% for explored_property in explorable_properties %}
{% if explored_property.__toString() == property.__toString() %}
{% include 'components/property.html.twig' with {'property': explored_property} %}
{% endif %}
{% endfor %}
{% set treated_properties = treated_properties|merge([property.__toString()]) %}
{% endif %}
{% endfor %}
</section>
{% endif %}
4 changes: 2 additions & 2 deletions tools/php_api_ref/.phpdoc/template/components/tags.html.twig
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
{% set tags = node.tags|filter((v,k) => k not in excluded_tags and not (k starts with 'phpstan-')) %}
{% set has_tags = false %}
{% for name,seriesOfTag in tags %}
{% if name in ['see', 'uses'] %}
{% if name in ['see', 'uses', 'used-by'] %}
{% set seriesOfTag = seriesOfTag|filter(tag => '<a ' in tag.reference|route('class:short')) %}
{% endif %}
{% if seriesOfTag|length > 0 %}
Expand All @@ -19,7 +19,7 @@
</h5>
<dl class="phpdocumentor-tag-list">
{% for name,seriesOfTag in tags %}
{% if name in ['see', 'uses'] %}
{% if name in ['see', 'uses', 'used-by'] %}
{% set seriesOfTag = seriesOfTag|filter(tag => '<a ' in tag.reference|route('class:short')) %}
{% endif %}
{% for tag in seriesOfTag %}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
{% set breadcrumbs = usesNamespaces ? breadcrumbs(node) : packages(node) %}
{% set fqcn = breadcrumbs|map(breadcrumb => breadcrumb.name)|join('\\') ~ '\\' ~ node.name %}

{% embed 'components/content-header.html.twig' with {
anchor: node.name,
anchor_link: '#' ~ node.name,
fqcn,
add_edition: true,
} %}
{% block subheader %}
<div class="content-header__subheader">Trait</div>

{% if node.usedTraits is not empty %}
<div class="content-header__subheader">
Uses
{% for trait in node.usedTraits %}
{{ trait|route('class:short') }}{% if not loop.last %}, {% endif %}
{% endfor %}
</div>
{% endif %}
{% endblock %}
{% endembed %}
5 changes: 5 additions & 0 deletions tools/php_api_ref/.phpdoc/template/css/base.css.twig
Original file line number Diff line number Diff line change
Expand Up @@ -256,6 +256,11 @@ ul.breadcrumbs li.breadcrumb-item-current span {
border: 1px solid var(--ibexa-jazzberry);
}

.md-typeset .content-header .optional-pill {
color: var(--sherpa-blue);
border: 1px solid var(--sherpa-blue);
}

.md-typeset .content-header img {
display: inline-block;
margin-bottom: -2px;
Expand Down
8 changes: 8 additions & 0 deletions tools/php_api_ref/.phpdoc/template/css/custom.css.twig
Original file line number Diff line number Diff line change
Expand Up @@ -540,6 +540,14 @@ div.pills {
background-color: var(--ibexa-jazzberry);
}

.optional-pill::after {
content: "Optional";
}

.optional-pill {
background-color: var(--sherpa-blue);
}

.md-clipboard:focus, .md-clipboard:hover {
color: var(--ibexa-jazzberry);
}
Expand Down
2 changes: 1 addition & 1 deletion tools/php_api_ref/.phpdoc/template/interface.html.twig
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
{% block content %}
{% include 'components/breadcrumbs.html.twig' %}
{% include 'components/interface-title.html.twig' %}
{% include('components/element-header.html.twig') %}
{% include 'components/element-header.html.twig' %}
{% include 'components/constants.html.twig' %}
{% include 'components/methods.html.twig' %}
{% endblock %}
Expand Down
10 changes: 10 additions & 0 deletions tools/php_api_ref/.phpdoc/template/js/external-links.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
$(() => {
$('abbr').each((index, element) => {
let $this = $(element);
let fqcn = $this.attr('title');
if (fqcn.startsWith('\\Symfony\\') && 'a' != $this.parent().prop('tagName')) {
let href = 'https://github.com/symfony/symfony/blob/' + symfonyVersion + '/src' + fqcn.replaceAll('\\', '/') + '.php';
$this.wrap('<a href="' + href + '" class="external">');
}
});
})
1 change: 1 addition & 0 deletions tools/php_api_ref/.phpdoc/template/layout.html.twig
Original file line number Diff line number Diff line change
Expand Up @@ -68,5 +68,6 @@
<script src="js/search_custom.js"></script>
<script src="js/copy_to_clipboard.js"></script>
<script src="js/version_switcher_custom.js"></script>
<script src="js/external-links.js"></script>
</body>
</html>
89 changes: 89 additions & 0 deletions tools/php_api_ref/.phpdoc/template/trait.html.twig
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
{% extends 'base.html.twig' %}

{% block title %}{{ node.name }} | {{ parent() }}{% endblock %}
{% block meta %}
<meta name="description" content="{{ node.summary|escape }}" />
{{ parent() }}
{% endblock %}

{% block content %}
{% include 'components/breadcrumbs.html.twig' %}
{% include 'components/trait-title.html.twig' %}
{% include 'components/element-header.html.twig' %}
{% include 'components/constants.html.twig' %}
{% include 'components/properties.html.twig' %}
{% include 'components/methods.html.twig' %}
{% endblock %}

{% block on_this_page %}
{% set constants = constants(node) %}
{% set properties = properties(node) %}
{% set methods = methods(node) %}

{% if constants is not empty or properties is not empty or methods is not empty %}
<label class="md-nav__title" for="__toc" title="{{ node.name }}">
{{ node.name }}
</label>
{% endif %}

<ul class="md-nav__list">
{% if constants is not empty %}
<li class="md-nav__item level-1 with-children">
<a href="{{ node|route("url")|raw }}#constants" title="Constants" class="md-nav__link">
Constants
</a>
<nav class="md-nav">
<ul class="md-nav__list">
{% for constant in constants|sortByVisibility %}
<li class="md-nav__item level-2">
<a href="{{ link(constant) }}" title="{{ constant.name }}" class="md-nav__link">
{{ constant.name }}
</a>
</li>
{% endfor %}
</ul>
</nav>
</li>
{% endif %}
{% if properties is not empty %}
<li class="md-nav__item level-1 with-children">
<a href="{{ node|route("url")|raw }}#properties" title="Properties" class="md-nav__link">
Properties
</a>
<nav class="md-nav">
<ul class="md-nav__list">
{% set treated_properties = [] %}
{% for property in properties|sortByVisibility %}
{% if property.__toString() not in treated_properties %}
<li class="md-nav__item level-2">
<a href="{{ link(property) }}" title="{{ property.name }}" class="md-nav__link">
{{ property.name }}
</a>
</li>
{% set treated_properties = treated_properties|merge([property.__toString()]) %}
{% endif %}
{% endfor %}
</ul>
</nav>
</li>
{% endif %}
{% if methods is not empty %}
<li class="md-nav__item level-1 with-children">
<a href="{{ node|route("url")|raw }}#methods" title="Methods" class="md-nav__link">
Methods
</a>
<nav class="md-nav">
<ul class="md-nav__list">
{% for method in methods|sortByVisibility %}
<li class="md-nav__item level-2">
<a href="{{ link(method) }}" title="{{ method.name }}" class="md-nav__link">
{{ method.name }}()
</a>
</li>
{% endfor %}
</ul>
</nav>
</li>
{% endif %}
</ul>
{% endblock %}
7 changes: 7 additions & 0 deletions tools/php_api_ref/phpdoc.sh
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ OUTPUT_DIR=${2:-./docs/api/php_api/php_api_reference}; # Path to the directory w

DXP_EDITION='commerce'; # Edition from and for which the Reference is built
DXP_VERSION='4.6.*'; # Version from and for which the Reference is built
DXP_ADD_ONS=(connector-ai connector-openai); # Packages not included in $DXP_EDITION but added to the Reference, listed without their vendor "ibexa"
DXP_EDITIONS=(oss headless experience commerce); # Available editions ordered by ascending capabilities
PHPDOC_VERSION='3.5.3'; # Version of phpDocumentor used to build the Reference
PHPDOC_CONF="$(pwd)/tools/php_api_ref/phpdoc.dist.xml"; # Absolute path to phpDocumentor configuration file
Expand Down Expand Up @@ -63,6 +64,12 @@ fi;

export COMPOSER_ROOT_VERSION=$DXP_VERSION;

if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
for additional_package in "${DXP_ADD_ONS[@]}"; do
composer require --no-interaction --ignore-platform-reqs --no-scripts ibexa/$additional_package:$DXP_VERSION
done;
fi;

#if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
# MY_PACKAGE='';
# MY_BRANCH='';
Expand Down

0 comments on commit f6f0894

Please sign in to comment.