1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
---
title: git.sr.ht annotations reference
---
Annotations are a feature of git.sr.ht which allows you to upload arbitrary
*annotations* to files in your source code, which will then be shown on the web.
An example repo with annotations configured is
[~sircmpwn/scdoc](https://git.sr.ht/~sircmpwn/scdoc), where they are used to
link C function calls to their definitions.
To add annotations to your repo, you'll need to have a builds.sr.ht [set
up](https://man.sr.ht/tutorials/getting-started-with-builds.md), and find an
annotation generator for your project's programming language(s):
- C: [annotatec](https://git.sr.ht/~sircmpwn/annotatec)
- Go: [annotatego](https://git.sr.ht/~sircmpwn/annotatego)
- POSIX shell: [annotatesh](https://git.sr.ht/~emersion/annotatesh)
- Python: [annotatepy](https://git.sr.ht/~ihabunek/annotatepy)
- Rust: [annotate-rust](https://git.sr.ht/~wezm/annotate-rust)
If your language isn't listed here, see [writing custom
annotators](#writing-custom-annotators).
See each annotator's instructions for generating the annotation file. You'll
then need to add an OAuth token to builds.sr.ht - go to your [oauth
settings](https://meta.sr.ht/oauth) and generate a personal access token, then
paste the generated token into [builds.sr.ht
secrets](https://builds.sr.ht/secrets) like this:
```sh
#!/bin/sh
oauth_token=# your oauth token here
curl -X PUT \
-H "Authorization: token $oauth_token" \
-H "Content-Type: application/json" \
-d @"$1" \
https://git.sr.ht/api/"~$2"/repos/"$3"/$(git rev-parse HEAD)/annotate
```
Set the path to `~/upload-annotations` and the file mode to 755, then add the
UUID to the secrets list in your build manifest. Call the annotator to generate
annotations for your code, then use the secret script to upload them. The result
will look something like this:
```
# ...
secrets:
- your-uuid-here
tasks:
# ...
- annotate: |
cd your-project
find . -name "*.c" | xargs annotatec -g > annotations.json
../upload-annotations annotations.json your-username your-reponame
```
## Writing custom annotators
The annotations.json format is a mapping of blob IDs to annotations. The blob ID
is the ID of the blob which the annotations supplement, you can find it for a
given file like so:
git ls-tree HEAD path/to/file.c
When writing an annotator, you may find it useful to add the `-r` flag to scan
the entire git tree at once, and `-z` to make the output more easily machine
readable. See [`git-ls-tree(1)`](https://git-scm.com/docs/git-ls-tree) for
details on this command.
Once you have the blob ID, you can specify a list of annotations. Each
annotation must have a `type`, which can be one of the following:
### "type": "link"
This annotates your code with a link, either an external link or a link to
another part of your source code.
```json
{
"type": "link",
"lineno": integer,
"colno": integer,
"len": integer,
"to": "url...",
"title": "anchor title attribute", (optional)
"color": "background color (#RRGGBB or 'transparent')" (optional)
}
```
If `to` is a relative URL, it will be assumed to be a link to another part of
this repository's source tree. Otherwise it's used-as is, for example as a link
to some external documentation.
### "type": "markdown"
A markdown annotation adds an expandable annotation to the end of the annotated
line, which when clicked, shows an arbitrary markdown snippet.
```json
{
"type": "markdown",
"lineno": integer,
"title": "title of the annotation",
"content": "markdown text..."
}
```
## Full example
Here is a complete example of a valid annotations JSON:
```json
{
"98bc0394a2f15171fb113acb5a9286a7454f22e7": [
{
"type": "markdown",
"lineno": 33,
"title": "2 references",
"content": "- [../main.c:123](https://example.org)\n- [../main.c:321](https://example.org)"
},
{
"type": "link",
"lineno": 38,
"colno": 7,
"len": 15,
"to": "#L6"
},
{
"type": "link",
"lineno": 34,
"colno": 13,
"len": 11,
"to": "src/utf8_encode.c#L5"
},
{
"type": "link",
"lineno": 41,
"colno": 2,
"len": 11,
"to": "src/utf8_encode.c#L5"
}
]
}
```
|
