The xref macro is for cross references to internal links within the documentation, not external links. xref:https://… results in an anchor link. The existing doc-links test didn't catch this, because it operates at the HTTP level. But the problem is easy to spot in the sources, so I've added a new check that just greps for this pattern. Reported-by: Ryan Lahfa <ryan@lahfa.xyz> Fixes: 97cceff ("Documentation: add contributing information") Signed-off-by: Alyssa Ross <hi@alyssa.is> --- v1: https://spectrum-os.org/lists/archives/spectrum-devel/20230527151106.2015901... doc-anchors.nix didn't actually ever succeed in v1, oops. Documentation/contributing/communication.adoc | 26 +++++++++---------- Documentation/contributing/index.adoc | 2 +- .../contributing/writing_documentation.adoc | 18 ++++++------- release/checks/default.nix | 2 ++ release/checks/doc-anchors.nix | 12 +++++++++ 5 files changed, 37 insertions(+), 23 deletions(-) create mode 100644 release/checks/doc-anchors.nix diff --git a/Documentation/contributing/communication.adoc b/Documentation/contributing/communication.adoc index 506fa28..8288c99 100644 --- a/Documentation/contributing/communication.adoc +++ b/Documentation/contributing/communication.adoc @@ -27,17 +27,17 @@ Spectrum's developers, subscribe to *announce@spectrum-os.org*. You can discuss Spectrum and related topics in real time on IRC, or more long-form on spectrum-announce (_discuss@spectrum-os.org_). Finally, development work happens in Spectrum's -xref:https://spectrum-os.org/git/[source repositories], and is -discussed on spectrum-devel (_devel@spectrum-os.org_). +https://spectrum-os.org/git/[source repositories], and is discussed on +spectrum-devel (_devel@spectrum-os.org_). == Internet Relay Chat There is a single Internet Relay Chat (IRC) channel, -xref:ircs://irc.libera.chat:6697/spectrum[#spectrum] -on xref:https://libera.chat/[Libera.Chat], for all kinds of Spectrum -discussions. You can also join through xref:https://matrix.org/[Matrix] as -xref:https://matrix.to/#/#spectrum:libera.chat[#spectrum:libera.chat]. +link:ircs://irc.libera.chat:6697/spectrum[#spectrum] on +https://libera.chat/[Libera.Chat], for all kinds of Spectrum +discussions. You can also join through https://matrix.org/[Matrix] as +https://matrix.to/#/#spectrum:libera.chat[#spectrum:libera.chat]. If you are new to IRC, you might find Matrix the easiest way to get started. The channel is *logged*, but the logs are not available online yet. @@ -49,11 +49,11 @@ following along with it, the best thing to do is subscribe to one or more of the Spectrum mailing lists. If mailing lists are not your thing, that is okay! Try the -xref:https://spectrum-os.org/lists/hyperkitty/[Web UI], which allows -you to interact with the mailing lists much like a modern web forum. +https://spectrum-os.org/lists/hyperkitty/[Web UI], which allows you to +interact with the mailing lists much like a modern web forum. -Each list has xref:https://spectrum-os.org/lists/archives/[archives] -that can also be accessed via the web, NNTP or Atom. You are strongly +Each list has https://spectrum-os.org/lists/archives/[archives] that +can also be accessed via the web, NNTP or Atom. You are strongly encouraged to mirror them. [cols="1,1"] @@ -64,14 +64,14 @@ encouraged to mirror them. from Spectrum's developers will be posted. You can subscribe -xref:https://spectrum-os.org/lists/mailman3/lists/announce.spectrum-os.org/[on the web], +https://spectrum-os.org/lists/mailman3/lists/announce.spectrum-os.org/[on the web], or by sending mail to *announce-subscribe@spectrum-os.org*. |discuss@spectrum-os.org |This list contains high-level discussion about the project. You can subscribe -xref:https://spectrum-os.org/lists/mailman3/lists/discuss.spectrum-os.org/[on the web], +https://spectrum-os.org/lists/mailman3/lists/discuss.spectrum-os.org/[on the web], or by sending mail to *discuss-subscribe@spectrum-os.org*. |devel@spectrum-os.org @@ -84,6 +84,6 @@ For more information, see xref:working-with-patches.adoc[Working with Patches]. You can subscribe -xref:https://spectrum-os.org/lists/mailman3/lists/devel.spectrum-os.org/[on the web], or by sending mail to *devel-subscribe@spectrum-os.org*. +https://spectrum-os.org/lists/mailman3/lists/devel.spectrum-os.org/[on the web], or by sending mail to *devel-subscribe@spectrum-os.org*. |=== diff --git a/Documentation/contributing/index.adoc b/Documentation/contributing/index.adoc index 48255d8..03eac68 100644 --- a/Documentation/contributing/index.adoc +++ b/Documentation/contributing/index.adoc @@ -48,7 +48,7 @@ There is also a web interface https://spectrum-os.org/lists/hyperkitty/ that you can use to browse or even post to the mailing list. Add a Signed-off-by line to each patch you submit, to indicate your -certification of the xref:https://spectrum-os.org/git/spectrum/tree/DCO-1.1.txt[Developer's Certificate of Origin] for that patch. +certification of the https://spectrum-os.org/git/spectrum/tree/DCO-1.1.txt[Developer's Certificate of Origin] for that patch. The easiest way to do this is with `git commit's -s` flag. Do not be too afraid of getting it wrong the first couple of times. diff --git a/Documentation/contributing/writing_documentation.adoc b/Documentation/contributing/writing_documentation.adoc index f8a69ef..cb09241 100644 --- a/Documentation/contributing/writing_documentation.adoc +++ b/Documentation/contributing/writing_documentation.adoc @@ -11,11 +11,11 @@ formatting, and organizing the Spectrum documentation. Please follow these guidelines and conventions when editing the documentation. -We use xref:https://nixos.org/manual/nix/stable/introduction.html[Nix] -and xref:https://github.com/just-the-docs/just-the-docs[Just the Docs] -for building the documentation. Sources are written in AsciiDoc -If you are new with it, -see xref:https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation]. +We use https://nixos.org/manual/nix/stable/introduction.html[Nix] and +https://github.com/just-the-docs/just-the-docs[Just the Docs] for +building the documentation. Sources are written in AsciiDoc If you are +new with it, see +https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation]. If you want to test your changes, see xref:../contributing/building-documentation.adoc[Building Documentation]. @@ -38,7 +38,7 @@ to suit your changing needs. == Document Layout -* xref:https://docs.asciidoctor.org/asciidoc/latest/document/header/[Document header]: +* https://docs.asciidoctor.org/asciidoc/latest/document/header/[Document header]: include your name and a revision line following the author line. Example: = Document Title @@ -64,15 +64,15 @@ abbreviations are used. ** Keep text hard-wrapped at 70-80 characters. (Most editors should be able to do this automatically.) This makes it easier to pick out specific parts in review, and also makes it easier to read in some editors. (It does not make a difference to the result as rendered in the web browser.) -** Keep the text in the description attribute hard-wrapped as well. For more information, see the xref:https://docs.asciidoctor.org/asciidoc/latest/document/metadata/#description[Document Metadata] section of the Asciidoctor Docs. +** Keep the text in the description attribute hard-wrapped as well. For more information, see the https://docs.asciidoctor.org/asciidoc/latest/document/metadata/#description[Document Metadata] section of the Asciidoctor Docs. -* Put one sentence on each line. This makes it easy to move content around, and also easy to spot (too) long sentences. For more information, see xref:https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[AsciiDoc Recommended Practices]. +* Put one sentence on each line. This makes it easy to move content around, and also easy to spot (too) long sentences. For more information, see https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[AsciiDoc Recommended Practices]. == Structure * Use subheading to organize information. * One topic per article. -* To make accents, use xref:https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/[admonitions]. +* To make accents, use https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/[admonitions]. * Use numbered lists for actions that happen in sequence. * Do not use parenthesis for additional information, make a separate sentence instead. diff --git a/release/checks/default.nix b/release/checks/default.nix index f8a3f9b..100de9a 100644 --- a/release/checks/default.nix +++ b/release/checks/default.nix @@ -8,6 +8,8 @@ import ../../lib/eval-config.nix ({ ... } @ args: doc-links = import ./doc-links.nix args; + doc-anchors = import ./doc-anchors.nix args; + pkg-tests = import ./pkg-tests.nix args; reuse = import ./reuse.nix args; diff --git a/release/checks/doc-anchors.nix b/release/checks/doc-anchors.nix new file mode 100644 index 0000000..1fae7e3 --- /dev/null +++ b/release/checks/doc-anchors.nix @@ -0,0 +1,12 @@ +# SPDX-License-Identifier: MIT +# SPDX-FileCopyrightText: 2023 Alyssa Ross <hi@alyssa.is> + +import ../../lib/eval-config.nix ({ config, ... }: +config.pkgs.callPackage ({ runCommand }: + +runCommand "spectrum-doc-anchors" {} '' + cd ${(import ../../Documentation { inherit config; }).src} + ! grep --color=always -r xref:http + touch $out +'' +) { }) base-commit: 1c6893145bdf023cd03b7675a18749ce8ed3803f -- 2.37.1