Skip to content

Commit d1d83ad

Browse files
committed
Improve documentation
1 parent 9747283 commit d1d83ad

9 files changed

Lines changed: 266 additions & 238 deletions

File tree

docs/5.0/bounds.md

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,6 @@ The parsers return the same array representation of the interval with the follow
3333
- `end`: the end or upper bound as a string
3434
- `bounds`: the end or upper bound as a `Bounds` Enumeration
3535

36-
#### Examples
37-
3836
~~~php
3937
use League\Period\Bounds;
4038

@@ -56,8 +54,6 @@ Bounds::buildBourbaki(string $lowerBound, string $upperBound): string;
5654
On the opposite, the `Bounds` enum can format an interval by decorating the interval string representation.
5755
You can specify which format you want to use, the ISO or the Boubarki one through the dedicated method.
5856

59-
#### Examples
60-
6157
~~~php
6258
use League\Period\Bounds;
6359

@@ -76,8 +72,6 @@ public Bounds::isStartIncluded(): bool
7672
public Bounds::isEndIncluded(): bool
7773
~~~
7874

79-
#### Examples
80-
8175
~~~php
8276
use League\Period\Bounds;
8377

@@ -94,8 +88,6 @@ public Bounds::equalsStart(Bound $other): bool
9488
public Bounds::equalsEnd(Bound $other): bool
9589
~~~
9690

97-
#### Examples
98-
9991
~~~php
10092
use League\Period\Bounds;
10193

@@ -118,8 +110,6 @@ public Bounds::replaceStart(Bounds $other): Bounds
118110
public Bounds::replaceEnd(Bounds $other): Bounds
119111
~~~
120112

121-
#### Examples
122-
123113
~~~php
124114
use League\Period\Bounds;
125115

docs/5.0/datepoint.md

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,6 @@ public DatePoint::fromDate(DateTimeInterface $date): self;
2323
~~~
2424

2525
Returns a `DatePoint` from a `DateTimeInterface` implementing object
26-
27-
#### example
2826

2927
~~~php
3028
use League\Period\DatePoint;
@@ -46,8 +44,6 @@ Returns a `DatePoint` from a string parsable by the `DateTimeImmutable` construc
4644
<p class="message-info">Because we are using PHP's parser, values exceeding ranges will be added to their parent values.</p>
4745
<p class="message-info">If no timezone information is given, the returned <code>DatePoint</code> object will use the current timezone.</p>
4846

49-
#### examples
50-
5147
~~~php
5248
use League\Period\DatePoint;
5349

@@ -70,8 +66,6 @@ Returns a `DatePoint` from an integer interpreted as a timestamp.
7066

7167
<p class="message-info">The timezone will always be <code>UTC</code>.</p>
7268

73-
#### examples
74-
7569
Using the `$datepoint` argument
7670

7771
~~~php
@@ -88,8 +82,6 @@ public readonly DateTimeImmutable DatePoint::date;
8882
At any given moment you can easily access the underlying `DateTimeImmutable` instance by
8983
calling the public readonly property `DatePoint::date`.
9084

91-
#### examples
92-
9385
~~~php
9486
use League\Period\DatePoint;
9587

@@ -126,8 +118,6 @@ For each a these methods a `Period` object is returned with:
126118
- the starting date endpoint represents the beginning of the current date endpoint calendar interval;
127119
- the duration associated with the given calendar interval;
128120

129-
#### Examples
130-
131121
~~~php
132122
use League\Period\Bounds;
133123
use League\Period\DatePoint;
@@ -163,8 +153,6 @@ where `method` is one of the basic relation between a datepoint and an interval.
163153
- `DatePoint::abuts`
164154
- `DatePoint::isAfter`
165155

166-
#### Examples
167-
168156
~~~php
169157
use League\Period\Bounds;
170158
use League\Period\DatePoint;

docs/_data/manifest.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
2-
"docs.css": "/styles.0006.css",
3-
"docs.js": "/scripts.0004.js"
2+
"docs.css": "/styles.css",
3+
"docs.js": "/scripts.js"
44
}

docs/_layouts/default.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
<link rel="preconnect" href="https://fonts.googleapis.com">
2020
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
2121
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@300;400;500&family=Onest:wght@300;400;500;600;700;900&display=swap" rel="stylesheet">
22-
<link href="{{ site.data.manifest['docs.css'] }}" rel="stylesheet">
22+
<link href="{{ site.data.manifest['docs.css'] }}?v={{ site.time | date:'%s' }}" rel="stylesheet">
2323
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css">
2424
<script async src="https://www.googletagmanager.com/gtag/js?id={{ site.data.project.google_analytics_tracking_id }}"></script>
2525
<script>
@@ -42,7 +42,7 @@
4242
<input type="search" id="doc-search" class="w-64" placeholder="search the docs...">
4343
</div>
4444
</header>
45-
<main class="relative flex justify-center mx-auto max-w-8xl sm:px-2 lg:px-8 xl:px-12">
45+
<main class="relative flex justify-center mx-auto max-w-8xl sm:px-2 lg:px-8 xl:px-12 gap-8">
4646
<label for="navigation" class="fixed top-5 right-5 z-50 flex items-center justify-center w-12 h-12 mb-4 ml-4 bg-white border rounded-full shadow-lg cursor-pointer text-slate-600 border-slate-300 lg:hidden transition duration-200 ease-in-out active:scale-95">
4747
<svg xmlns="http://www.w3.org/2000/svg" class="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
4848
<path stroke-linecap="round" stroke-linejoin="round" d="M4 8h16M4 16h16" />
@@ -183,7 +183,7 @@ <h3 class="font-semibold tracking-tight text-slate-900">Older versions</h3>
183183
</div>
184184
</footer>
185185
</div>
186-
<script src="{{ site.data.manifest['docs.js'] }}"></script>
186+
<script src="{{ site.data.manifest['docs.js'] }}?v={{ site.time | date:'%s' }}"></script>
187187
<script src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
188188
<script> docsearch({
189189
apiKey: '0b444a337a024ecded8e2da9367775fa',

docs/_layouts/index.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
<link rel="preconnect" href="https://fonts.googleapis.com">
1212
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
1313
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@300;400;500&family=Onest:wght@300;400;500;600;700;900&display=swap" rel="stylesheet">
14-
<link href="{{ site.data.manifest['docs.css'] }}" rel="stylesheet">
14+
<link href="{{ site.data.manifest['docs.css'] }}?v={{ site.time | date:'%s' }}" rel="stylesheet">
1515
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-46050814-6"></script>
1616
<script>
1717
window.dataLayer = window.dataLayer || [];

docs/_layouts/redirect.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
<link rel="preconnect" href="https://fonts.googleapis.com">
2020
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
2121
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@300;400;500&family=Onest:wght@300;400;500;600;700;900&display=swap" rel="stylesheet">
22-
<link href="{{ site.data.manifest['docs.css'] }}" rel="stylesheet">
22+
<link href="{{ site.data.manifest['docs.css'] }}?v={{ site.time | date:'%s' }}" rel="stylesheet">
2323
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css">
2424
<script async src="https://www.googletagmanager.com/gtag/js?id={{ site.data.project.google_analytics_tracking_id }}"></script>
2525
<script>
@@ -42,7 +42,7 @@
4242
<input type="search" id="doc-search" class="w-64" placeholder="search the docs...">
4343
</div>
4444
</header>
45-
<main class="relative flex justify-center mx-auto max-w-8xl sm:px-2 lg:px-8 xl:px-12">
45+
<main class="relative flex justify-center mx-auto max-w-8xl sm:px-2 lg:px-8 xl:px-12 gap-8">
4646
<label for="navigation" class="fixed top-5 right-5 z-50 flex items-center justify-center w-12 h-12 mb-4 ml-4 bg-white border rounded-full shadow-lg cursor-pointer text-slate-600 border-slate-300 lg:hidden transition duration-200 ease-in-out active:scale-95">
4747
<svg xmlns="http://www.w3.org/2000/svg" class="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
4848
<path stroke-linecap="round" stroke-linejoin="round" d="M4 8h16M4 16h16" />
@@ -174,7 +174,7 @@ <h1>Redirecting…</h1>
174174
</div>
175175
</footer>
176176
</div>
177-
<script src="{{ site.data.manifest['docs.js'] }}"></script>
177+
<script src="{{ site.data.manifest['docs.js'] }}?v={{ site.time | date:'%s' }}"></script>
178178
<script src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
179179
<script> docsearch({
180180
apiKey: '0b444a337a024ecded8e2da9367775fa',

docs/input.css

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -542,33 +542,28 @@ img {
542542
}
543543
}
544544

545-
546545
#onthispage {
547-
@apply sticky top-[4.5rem] h-[calc(100vh-4.5rem)] w-72 overflow-y-auto pr-8 text-sm xl:pr-16 self-start hidden lg:block;
546+
@apply sticky top-[4.5rem] h-[calc(100vh-4.5rem)] w-72 overflow-y-auto pr-8 text-sm xl:pr-16 self-start hidden lg:block shrink-0;
548547
}
549548

550549
#onthispage nav h3 {
551-
@apply font-semibold tracking-tight text-slate-900
550+
@apply font-semibold tracking-tight text-slate-900;
552551
}
553552

554553
#onthispage ul {
555-
@apply pl-3 mt-3 space-y-2
554+
@apply pl-3 mt-3 space-y-2;
556555
}
557556

558557
#onthispage a {
559-
display:block;
560-
border-left: 2px solid transparent;
561-
padding-left: 0.5rem;
562-
text-decoration: none;
558+
@apply block border-l-2 border-transparent pl-2 no-underline;
563559
}
564560

565561
#onthispage a:hover {
566-
text-decoration: underline;
562+
@apply underline;
567563
}
568564

569565
#onthispage .active {
570-
color: #b78e1d; /* Tailwind blue-600 */
571-
border-left-color: #b78e1d;
566+
@apply text-period-dark border-l-period-dark;
572567
}
573568

574569
html {
Lines changed: 79 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,55 @@
1+
(() => {
2+
const root = document.querySelector('article.content');
3+
if (!root) return;
4+
5+
const isHeading = el => el && el.nodeType === 1 && /^H[1-6]$/.test(el.tagName);
6+
const headers = root.querySelectorAll('h2, h3, h4, h5, h6');
7+
const ids = new Set();
8+
headers.forEach(h => {
9+
let id = h.id || h.textContent.trim().toLowerCase().replace(/\W+/g, '-');
10+
let base = id;
11+
let i = 2;
12+
while (ids.has(id)) id = `${base}-${i++}`;
13+
ids.add(id);
14+
h.id = id;
15+
});
16+
17+
for (const h of Array.from(headers)) {
18+
// Idempotence : si ce titre est déjà le 1er enfant d'un .section-wrapper, on ne fait rien
19+
if (h.parentElement?.classList.contains('section-wrapper') &&
20+
h.parentElement.firstElementChild === h) {
21+
continue;
22+
}
23+
24+
const wrapper = document.createElement('div');
25+
wrapper.className = 'section-wrapper';
26+
// (optionnel) pour debug :
27+
wrapper.dataset.heading = h.tagName.toLowerCase();
28+
if (h.id) wrapper.dataset.anchor = h.id;
29+
30+
// Insérer le wrapper juste avant le titre
31+
h.parentNode.insertBefore(wrapper, h);
32+
33+
// Déplacer le titre dans le wrapper
34+
wrapper.appendChild(h);
35+
36+
// Puis déplacer tout ce qui suit IMMÉDIATEMENT jusqu'au prochain heading (quel que soit le niveau)
37+
// -> ainsi on n'englobe jamais les sous-titres
38+
let node = wrapper.nextSibling; // ancien "nextSibling" du h2, devenu celui du wrapper
39+
while (node) {
40+
const next = node.nextSibling; // mémoriser avant déplacement/arrêt
41+
42+
// Si on tombe sur un titre (h1..h6), on s'arrête (le prochain wrapper le prendra en charge)
43+
if (node.nodeType === 1 && isHeading(node)) break;
44+
45+
// Sinon, c'est du contenu d'intro : on le rapatrie dans ce wrapper
46+
wrapper.appendChild(node);
47+
48+
node = next;
49+
}
50+
}
51+
})();
52+
153
(() => {
254
let contentHeaders= document.querySelectorAll("main h2[id]");
355
if (!document.querySelector('html').classList.contains('homepage') && contentHeaders) {
@@ -71,7 +123,7 @@
71123
const menuLinks = document.querySelectorAll('#onthispage a');
72124
const observer = new IntersectionObserver(entries => {
73125
entries.forEach(entry => {
74-
const id = entry.target.getAttribute("id");
126+
const id = entry.target.getAttribute("data-anchor");
75127
const link = document.querySelector(`#onthispage a[href="#${id}"]`);
76128

77129
if (entry.isIntersecting) {
@@ -80,11 +132,12 @@
80132
}
81133
});
82134
}, {
83-
rootMargin: "-50% 0px -50% 0px", // trigger when the section is centered in viewport
135+
root: null,
136+
rootMargin: "0px 0px -100% 0px",
84137
threshold: 0
85138
});
86139

87-
sections.forEach(section => observer.observe(section));
140+
sections.forEach(section => observer.observe(section.parentElement));
88141
}
89142

90143
// generate code snippet copy/paste
@@ -98,29 +151,28 @@
98151
link.classList.add("copy-snippet");
99152
link.innerHTML = "copy 📋";
100153
link.addEventListener('click', function (e) {
101-
let snippetParent = e.target.parentNode;
102-
let notification = snippetParent.querySelector('.copy-snippet-notification');
103-
let content = snippetParent.querySelector('pre').textContent;
104-
try {
105-
navigator.clipboard.writeText(content);
106-
notification.innerHTML = 'Copied!';
107-
notification.classList.add('bg-black');
108-
notification.classList.remove('hidden');
109-
setTimeout(() => {
110-
notification.classList.add('hidden');
111-
notification.classList.remove('bg-black');
112-
}, 500);
113-
} catch (err) {
114-
console.error('Failed to copy: ', err);
115-
notification.innerHTML = 'Copy failed!';
116-
notification.classList.add('bg-red-800');
117-
notification.classList.remove('hidden');
118-
setTimeout(() => {
119-
notification.classList.add('hidden');
120-
notification.classList.remove('bg-red-800');
121-
}, 500);
122-
}
123-
}, false);
154+
let snippetParent = e.target.parentNode;
155+
let notification = snippetParent.querySelector('.copy-snippet-notification');
156+
let content = snippetParent.querySelector('pre').textContent;
157+
try {
158+
navigator.clipboard.writeText(content);
159+
notification.innerHTML = 'Copied!';
160+
notification.classList.add('bg-black');
161+
notification.classList.remove('hidden');
162+
setTimeout(() => {
163+
notification.classList.add('hidden');
164+
notification.classList.remove('bg-black');
165+
}, 500);
166+
} catch (err) {
167+
notification.innerHTML = 'Copy failed!';
168+
notification.classList.add('bg-red-800');
169+
notification.classList.remove('hidden');
170+
setTimeout(() => {
171+
notification.classList.add('hidden');
172+
notification.classList.remove('bg-red-800');
173+
}, 500);
174+
}
175+
}, false);
124176
snippet.appendChild(link);
125177
});
126178

@@ -134,9 +186,7 @@
134186

135187
document.addEventListener('click', (event) => {
136188
if (!dropDownButton.contains(event.target) && !dropDownList.contains(event.target)) {
137-
dropDownList.classList.add('hidden');
189+
dropDownList.classList.add('hidden');
138190
}
139191
});
140192
})();
141-
142-

0 commit comments

Comments
 (0)