From: Alyssa Ross <hi@alyssa.is>
To: devel@spectrum-os.org
Cc: Ryan Lahfa <ryan@lahfa.xyz>
Subject: [PATCH] Documentation: fix accidental anchor links
Date: Sat, 27 May 2023 15:11:06 +0000 [thread overview]
Message-ID: <20230527151106.2015901-1-hi@alyssa.is> (raw)
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>
---
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 | 11 ++++++++
5 files changed, 36 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..71c2fc9
--- /dev/null
+++ b/release/checks/doc-anchors.nix
@@ -0,0 +1,11 @@
+# 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
+''
+) { })
base-commit: 1c6893145bdf023cd03b7675a18749ce8ed3803f
--
2.37.1
reply other threads:[~2023-05-27 15:11 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230527151106.2015901-1-hi@alyssa.is \
--to=hi@alyssa.is \
--cc=devel@spectrum-os.org \
--cc=ryan@lahfa.xyz \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://spectrum-os.org/git/crosvm
https://spectrum-os.org/git/doc
https://spectrum-os.org/git/mktuntap
https://spectrum-os.org/git/nixpkgs
https://spectrum-os.org/git/spectrum
https://spectrum-os.org/git/ucspi-vsock
https://spectrum-os.org/git/www
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).