Skip to content

Commit edc20ca

Browse files
kleisaukekleisauke
authored
doc: move sections to separate files (batch 1/2) (#4449)
* doc: fix links and code highlighting in developer-checklist.md * doc: revise H2 headers * doc: drop the video SECTION * doc: move the draw SECTION * doc: move the create SECTION * doc: move the colour SECTION * doc: fix formatting in libvips-colour.md * doc: move the basic and type SECTION * doc: move the vips SECTION * doc: move the morphology SECTION * doc: move the resample SECTION * CI: ensure docs option is tested on Linux * doc: add script to check if all symbols are listed * doc: add missing symbols caught by 27016bb
1 parent fe77c2e commit edc20ca

23 files changed

+714
-299
lines changed

‎.github/workflows/ci.yml

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ jobs:
1414
include:
1515
- name: "Linux x64 (Ubuntu 24.04) - GCC 14"
1616
os: ubuntu-24.04
17-
build: { cc: gcc-14, cxx: g++-14, linker: ld }
17+
build: { cc: gcc-14, cxx: g++-14, linker: ld, docs: true }
1818

1919
- name: "Linux x64 (Ubuntu 24.04) - Clang 18 with ASan and UBSan"
2020
os: ubuntu-24.04
@@ -39,7 +39,7 @@ jobs:
3939
run: |
4040
sudo apt-get update
4141
sudo apt-get install \
42-
meson pkg-config \
42+
meson gi-docgen pkg-config \
4343
libarchive-dev libcfitsio-dev libcgif-dev \
4444
libexif-dev libexpat1-dev libffi-dev \
4545
libfftw3-dev libheif-dev libheif-plugin-aomenc \
@@ -100,6 +100,7 @@ jobs:
100100
run:
101101
meson setup build
102102
-Ddebug=true
103+
-Ddocs=${{ matrix.build.docs && 'true' || 'false' }}
103104
-Ddeprecated=false
104105
-Dmagick=disabled
105106
|| (cat build/meson-logs/meson-log.txt && exit 1)
@@ -108,8 +109,8 @@ jobs:
108109
run: meson compile -C build
109110

110111
- name: Check libvips
111-
run: |
112-
meson test -C build \
112+
run:
113+
meson test -C build
113114
|| (cat build/meson-logs/testlog.txt && exit 1)
114115

115116
- name: Install libvips

‎doc/check-sections.py

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
#!/usr/bin/env python3
2+
3+
import sys
4+
import argparse
5+
import xml.etree.ElementTree as ET
6+
from pathlib import Path
7+
8+
9+
def register_all_namespaces(filename):
10+
namespaces = dict([node for _, node in ET.iterparse(filename, events=['start-ns'])])
11+
for ns in namespaces:
12+
ET.register_namespace(ns, namespaces[ns])
13+
14+
15+
def check_sections(args):
16+
tree = ET.parse(args.gir)
17+
root = tree.getroot()
18+
19+
register_all_namespaces(args.gir)
20+
namespace = {
21+
'goi': 'http://www.gtk.org/introspection/core/1.0',
22+
'glib': 'http://www.gtk.org/introspection/glib/1.0',
23+
}
24+
25+
namespace_node = root.find('goi:namespace', namespace)
26+
27+
file_dict = {}
28+
for file in args.files:
29+
content = Path(file).read_text()
30+
comment_start_idx = content.find('<!-- ')
31+
if comment_start_idx == -1:
32+
print(f'ERROR: File {file} does not contain a HTML comment',
33+
file=sys.stderr)
34+
sys.exit(1)
35+
36+
comment_end_idx = content.find(' -->', comment_start_idx)
37+
section_covers = content[comment_start_idx + 5:comment_end_idx]
38+
39+
file_dict[section_covers] = {'file': file, 'content': content}
40+
41+
tag_parser_dict = {
42+
f'{{{namespace['goi']}}}alias': lambda n, _ : f'[alias@{n.attrib['name']}]',
43+
f'{{{namespace['goi']}}}bitfield': lambda n, _ : f'[flags@{n.attrib['name']}]',
44+
f'{{{namespace['goi']}}}callback': lambda n, _ : f'[callback@{n.attrib['name']}]',
45+
f'{{{namespace['goi']}}}class': lambda n, _ : f'[class@{n.attrib['name']}]',
46+
f'{{{namespace['goi']}}}constructor': lambda n, p : f'[ctor@{p}{n.attrib['name']}]',
47+
f'{{{namespace['goi']}}}method': lambda n, p : f'[method@{p}{n.attrib['name']}]',
48+
f'{{{namespace['goi']}}}constant': lambda n, _ : f'[const@{n.attrib['name']}]',
49+
f'{{{namespace['goi']}}}enumeration': lambda n, _ : f'[enum@{n.attrib['name']}]',
50+
f'{{{namespace['goi']}}}function-macro': lambda n, _ : f'[func@{n.attrib['name']}]',
51+
f'{{{namespace['goi']}}}function': lambda n, p : f'[func@{p}{n.attrib['name']}]',
52+
# each struct has its own documentation
53+
# f'{{{namespace['goi']}}}record': lambda n, _ : f'[struct@{n.attrib['name']}]',
54+
# struct and enum members do not need to be listed
55+
# f'{{{namespace['goi']}}}field': lambda n, p : f'[struct@Vips.{p}{n.attrib['name']}]',
56+
# f'{{{namespace['goi']}}}member': lambda n, p : f'[enum@Vips.{p}{n.attrib['name']}]',
57+
}
58+
59+
exitcode = 0
60+
61+
parent_map = {c: p for p in namespace_node.iter() for c in p}
62+
for node in parent_map:
63+
if 'moved-to' in node.attrib:
64+
continue
65+
66+
child = node.find('goi:doc', namespace)
67+
if child is None:
68+
continue
69+
70+
filename = child.attrib['filename']
71+
section = next((k for k in file_dict.keys() if filename.startswith(k)), None)
72+
if section is None:
73+
continue
74+
75+
parser_method = tag_parser_dict.get(node.tag, None)
76+
if parser_method is None:
77+
continue
78+
79+
parent_name = parent_map.get(node, {}).attrib.get('name') or ''
80+
if parent_name == 'Vips':
81+
parent_name = ''
82+
if parent_name:
83+
parent_name += '.'
84+
85+
symbol = parser_method(node, parent_name)
86+
if f'* {symbol}' not in file_dict[section]['content']:
87+
print(f"ERROR: Symbol '{symbol}' is not listed in '{file_dict[section]['file']}'",
88+
file=sys.stderr)
89+
exitcode = 1
90+
91+
sys.exit(exitcode)
92+
93+
94+
def main():
95+
parser = argparse.ArgumentParser()
96+
parser.add_argument('--gir', help='input GIR file', type=Path)
97+
parser.add_argument('files', help='markdown files', type=Path, nargs=argparse.REMAINDER)
98+
99+
args = parser.parse_args()
100+
check_sections(args)
101+
102+
103+
if __name__ == '__main__':
104+
main()

‎doc/developer-checklist.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@ nina.jpg: 6048x4032 uchar, 3 bands, srgb, jpegload
2121

2222
I see:
2323

24-
```bash/usr/bin/time -f %M:%e vips resize nina.jpg x.jpg 0.1
24+
```bash
25+
$ /usr/bin/time -f %M:%e vips resize nina.jpg x.jpg 0.1
2526
123648:0.23
2627
```
2728

@@ -97,7 +98,7 @@ operations.
9798
libvips after version 8.13 has a system for enabling and disabling image load
9899
libraries at runtime, see:
99100

100-
https://www.libvips.org/2022/05/28/What's-new-in-8.13.html
101+
<https://www.libvips.org/2022/05/28/What's-new-in-8.13.html>
101102

102103
You can usually improve security and avoid memory spikes by only enabling
103104
the image formats you really need. If you are handling untrusted data,
@@ -116,7 +117,7 @@ There are two main checks that are very worthwhile:
116117

117118
1. Sanity check image dimensions to protect you from decompression
118119
bombs like those described at
119-
https://www.bamsoftware.com/hacks/deflate.html
120+
<https://www.bamsoftware.com/hacks/deflate.html>
120121

121122
2. Check for interlaced (also called progressive) images.
122123

‎doc/how-it-opens-files.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ array. libvips supports direct access for `.v`, 8-bit binary ppm/pbm/pnm,
3636
analyse and raw.
3737

3838
libvips has a special direct write mode where pixels can be written directly
39-
to the file image. This is used for the [draw operators](?q=draw).
39+
to the file image. This is used for the [draw operations](libvips-draw.html).
4040

4141
## Random access via load library
4242

‎doc/libvips-arithmetic.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
Title: Pixel arithmetic
22

3+
<!-- libvips/arithmetic -->
4+
35
# Pixel arithmetic
46

57
These operations perform pixel arithmetic, that is, they perform an
@@ -65,7 +67,7 @@ generally the principle is that the output type should be large enough to
6567
represent the whole range of possible values, except that int never becomes
6668
float.
6769

68-
## Arithmetic functions
70+
## Functions
6971

7072
* [method@Image.add]
7173
* [func@Image.sum]
@@ -181,7 +183,7 @@ float.
181183
* [method@Image.project]
182184
* [method@Image.profile]
183185

184-
## Arithmetic enumerations
186+
## Enumerations
185187

186188
* [enum@OperationMath]
187189
* [enum@OperationMath2]

‎doc/libvips-basic.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
Title: Aliases, helpers and macros
2+
3+
<!-- libvips/iofuncs/type.c -->
4+
5+
# Aliases, helpers and macros
6+
7+
A selection of basic aliases, [alias@GObject.Type] helpers and macro
8+
definitions used by libvips.
9+
10+
## Structs
11+
12+
* [struct@Area]
13+
* [struct@ArrayDouble]
14+
* [struct@ArrayImage]
15+
* [struct@ArrayInt]
16+
* [struct@Blob]
17+
* [struct@RefString]
18+
* [struct@SaveString]
19+
20+
## Aliases
21+
22+
* [alias@Pel]
23+
24+
## Callbacks
25+
26+
* [callback@CallbackFn]
27+
* [callback@SListMap2Fn]
28+
* [callback@SListMap4Fn]
29+
* [callback@SListFold2Fn]
30+
31+
## Functions
32+
33+
* [method@Area.copy]
34+
* [func@Area.free_cb]
35+
* [method@Area.unref]
36+
* [ctor@Area.new]
37+
* [ctor@Area.new_array]
38+
* [ctor@Area.new_array_object]
39+
* [method@Area.get_data]
40+
* [ctor@RefString.new]
41+
* [method@RefString.get]
42+
* [ctor@Blob.new]
43+
* [func@Blob.copy]
44+
* [method@Blob.get]
45+
* [method@Blob.set]
46+
* [ctor@ArrayDouble.new]
47+
* [ctor@ArrayDouble.newv]
48+
* [method@ArrayDouble.get]
49+
* [ctor@ArrayInt.new]
50+
* [ctor@ArrayInt.newv]
51+
* [method@ArrayInt.get]
52+
* [ctor@ArrayImage.new]
53+
* [ctor@ArrayImage.newv]
54+
* [ctor@ArrayImage.empty]
55+
* [method@ArrayImage.append]
56+
* [method@ArrayImage.get]
57+
* [func@value_set_area]
58+
* [func@value_get_area]
59+
* [func@value_get_save_string]
60+
* [func@value_set_save_string]
61+
* [func@value_set_save_stringf]
62+
* [func@value_get_ref_string]
63+
* [func@value_set_ref_string]
64+
* [func@value_get_blob]
65+
* [func@value_set_blob]
66+
* [func@value_set_blob_free]
67+
* [func@value_set_array]
68+
* [func@value_get_array]
69+
* [func@value_get_array_double]
70+
* [func@value_set_array_double]
71+
* [func@value_get_array_image]
72+
* [func@value_set_array_image]
73+
* [func@value_get_array_int]
74+
* [func@value_set_array_int]
75+
* [func@value_get_array_object]
76+
* [func@value_set_array_object]
77+
78+
## Function macros
79+
80+
* [func@DEPRECATED_FOR]
81+
* [func@DEPRECATED_MACRO_FOR]
82+
* [func@ARRAY_ADDR]

0 commit comments

Comments
 (0)