From 354970f31b3eac72c343aabcf426afb7add38ab8 Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Mon, 29 Jun 2020 10:20:48 -0400 Subject: git.sr.ht: remove annotations --- git.sr.ht/annotations.md | 145 ----------------------------------------------- git.sr.ht/index.md | 7 --- 2 files changed, 152 deletions(-) delete mode 100644 git.sr.ht/annotations.md (limited to 'git.sr.ht') diff --git a/git.sr.ht/annotations.md b/git.sr.ht/annotations.md deleted file mode 100644 index e1eaaa0..0000000 --- a/git.sr.ht/annotations.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -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) -- Java: [annotatejava](https://git.sr.ht/~serra/de.serra.srht.annotatejava) -- 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" - } - ] -} -``` diff --git a/git.sr.ht/index.md b/git.sr.ht/index.md index c90ee8e..091efdd 100644 --- a/git.sr.ht/index.md +++ b/git.sr.ht/index.md @@ -58,13 +58,6 @@ branch, along with the new tag (this can be made the default behavior by running "refs" page of your repository. To attach files to it, click the tag name (e.g. "2.3.4") and use the upload form on this page. -## Source code annotations - -You can generate annotations for your source code to display on git.sr.ht. These -may be used, for example, to implement language-aware "go to reference" or "go -to usage" annotations throughout your code. For more information [see this -document](annotations.md). - ## Push Options git.sr.ht supports some git push options, which can be specified with `-o -- cgit