Skip to content

Commit d4fd88c

Browse files
rimi-itkrimi-itk
committed
Updated REST documentation
1 parent c084a53 commit d4fd88c

6 files changed

Lines changed: 79 additions & 11 deletions

File tree

‎README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,19 @@ For development (and testing) a couple of useful tasks are defined:
5858
* f2-api-client:run: Run bin/f2-api-client inside docker compose setup, e.g. `task f2-api-client:run -- searchCases '{"q": "test", "count": 10}'`
5959
```
6060

61+
### F2 REST documentation
62+
63+
The F2 REST documentation is available only as a PDF (!), but we need something we can refer to. Therefore, we convert
64+
[the PDF](resources/f2-rest-docs/f2-rest-docs-v13.pdf) to HTML and serve that.
65+
66+
Run
67+
68+
``` shell
69+
task f2-rest-docs:serve
70+
```
71+
72+
and open <http://127.0.0.1:8787/>.
73+
6174
---
6275

6376
``` mermaid

‎Taskfile.yml‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22

33
version: '3'
44

5+
includes:
6+
f2-rest-docs:
7+
taskfile: resources/f2-rest-docs/
8+
dir: resources/f2-rest-docs/
9+
510
tasks:
611
default:
712
cmds:
@@ -81,8 +86,7 @@ tasks:
8186

8287
# https://mago.carthage.software/latest/en/guide/getting-started/
8388
mago:run:
84-
desc: 'Run all Mago steps (cf.
85-
https://mago.carthage.software/latest/en/guide/getting-started/)'
89+
desc: 'Run all Mago steps (cf. https://mago.carthage.software/latest/en/guide/getting-started/)'
8690
cmds:
8791
- task: mago:lint
8892
- task: mago:format
@@ -99,18 +103,21 @@ tasks:
99103
mago:analyze: *mago_command
100104

101105
f2-api-client:run:
102-
desc: 'Run bin/f2-api-client inside docker compose setup, e.g. `task {{.TASK}}
103-
-- searchCases ''{"q": "test", "count": 10}''`'
106+
desc: 'Run bin/f2-api-client inside docker compose setup, e.g. `task {{.TASK}} -- caseSearch ''test''`'
104107
cmds:
105108
- task: compose
106109
vars:
107110
TASK_ARGS: run --quiet --rm phpfpm php bin/f2-api-client
108111

109112
f2-api-client:debug:
110-
desc: 'Debug bin/f2-api-client inside docker compose setup, e.g. `task {{.TASK}}
111-
-- searchCases ''{"q": "test", "count": 10}''`'
113+
desc: 'Debug bin/f2-api-client inside docker compose setup, e.g. `task {{.TASK}} -- caseSearch ''test''`'
112114
cmds:
113115
- task: compose
114116
vars:
115-
TASK_ARGS: run --quiet --env PHP_XDEBUG_MODE=debug --rm phpfpm php
116-
bin/f2-api-client
117+
TASK_ARGS: run --quiet --env PHP_XDEBUG_MODE=debug --rm phpfpm php bin/f2-api-client
118+
119+
f2-rest-docs:serve:
120+
desc: Build and serve F2 REST documentation as HTML
121+
cmds:
122+
- task: f2-rest-docs:html:generate
123+
- docker compose run --rm --publish 8787:8787 phpfpm php -S 0.0.0.0:8787 -t resources/f2-rest-docs/

‎resources/f2-rest-docs/Taskfile.yml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
# yaml-language-server: $schema=https://taskfile.dev/schema.json
2-
32
version: '3'
43

54
tasks:
@@ -12,8 +11,12 @@ tasks:
1211
- html:clean
1312
cmds:
1413
- docker run --volume $PWD:/app --workdir /app --rm minidocks/poppler pdftohtml f2-rest-docs-v13.pdf
14+
# Clean up
15+
- docker run --volume $PWD:/app --workdir /app --rm minidocks/poppler sed -i 's/target=\\"contents\\"/target="contents"/' f2-rest-docs-v13_ind.html
16+
# Add script in head element
17+
- docker run --volume $PWD:/app --workdir /app --rm minidocks/poppler sed -i '/<head>/r script.html' f2-rest-docs-v13_ind.html
1518

1619
html:clean:
1720
desc: Remove all generate HTML stuff
1821
cmds:
19-
- cmd: rm -f *.{html,png}
22+
- cmd: rm -f f2-rest-docs-*.{html,png}

‎resources/f2-rest-docs/f2-rest-docs-v13_ind.html‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,28 @@
11
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
22
<head>
3+
<script>
4+
addEventListener('load', () => {
5+
// Add URL fragment to parent location when clicking links.
6+
function setUrlFragment() {
7+
const url = new URL(this.href)
8+
console.log(url.hash)
9+
parent.location.hash = url.hash
10+
}
11+
12+
document.querySelectorAll('[href][target="contents"]').forEach(el => el.addEventListener('click', setUrlFragment))
13+
14+
// Click matching link when loading parent with URL fragment.
15+
const hash = parent.document.location.hash
16+
const link = document.querySelector(`[href$="${hash}"]`)
17+
if (null !== link) {
18+
link.click()
19+
}
20+
})
21+
</script>
322
<title></title>
423
</head>
524
<body>
6-
<a href="f2-rest-docs-v13s.html#outline" target=\"contents\">Outline</a><br/><a href="f2-rest-docs-v13s.html#1" target="contents" >Page 1</a><br/>
25+
<a href="f2-rest-docs-v13s.html#outline" target="contents">Outline</a><br/><a href="f2-rest-docs-v13s.html#1" target="contents" >Page 1</a><br/>
726
<a href="f2-rest-docs-v13s.html#2" target="contents" >Page 2</a><br/>
827
<a href="f2-rest-docs-v13s.html#3" target="contents" >Page 3</a><br/>
928
<a href="f2-rest-docs-v13s.html#4" target="contents" >Page 4</a><br/>

‎resources/f2-rest-docs/index.html‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<html>
2+
<head>
3+
<meta http-equiv="refresh" content="0; url=f2-rest-docs-v13.html" />
4+
</head>
5+
<body>
6+
</body>
7+
</html>

‎resources/f2-rest-docs/script.html‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<script>
2+
addEventListener('load', () => {
3+
// Add URL fragment to parent location when clicking links.
4+
function setUrlFragment() {
5+
const url = new URL(this.href)
6+
console.log(url.hash)
7+
parent.location.hash = url.hash
8+
}
9+
10+
document.querySelectorAll('[href][target="contents"]').forEach(el => el.addEventListener('click', setUrlFragment))
11+
12+
// Click matching link when loading parent with URL fragment.
13+
const hash = parent.document.location.hash
14+
const link = document.querySelector(`[href$="${hash}"]`)
15+
if (null !== link) {
16+
link.click()
17+
}
18+
})
19+
</script>

0 commit comments

Comments
 (0)