diff options
| -rw-r--r-- | git.sr.ht/annotations.md | 139 | ||||
| -rw-r--r-- | git.sr.ht/index.md | 5 |
2 files changed, 144 insertions, 0 deletions
diff --git a/git.sr.ht/annotations.md b/git.sr.ht/annotations.md new file mode 100644 index 0000000..ba19e90 --- /dev/null +++ b/git.sr.ht/annotations.md @@ -0,0 +1,139 @@ +--- +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) + +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"/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) +} +``` + +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" + } + ] +} +``` diff --git a/git.sr.ht/index.md b/git.sr.ht/index.md index a3407d0..0cbae4d 100644 --- a/git.sr.ht/index.md +++ b/git.sr.ht/index.md @@ -56,6 +56,11 @@ who has the link, but are not shown in your profile or in search results. Private repositories are only visible to you and other logged-in users who you explicitly [grant access to](#access). +## Source code annotations + +You can generate annotations for your source code to display on git.sr.ht. For +more information [see this document](annotations.md). + ## Settings Each repository's settings may be accessed via the settings link on the |