rst: Handle :doc:…/index references

The Sphinx "doc" role requires a full document name, i.e. being explicit about "index" pages. This makes sense as it's using filesystem semantics. Our rendering of rST to text for command-line help, however, turns "doc" roles into URLs and assumed URL semantics, i.e. where "/index.html" can be left implicit. This led to a semantic mismatch, which I noticed due to a "unknown reference" warning during the Sphinx build now that we include a (unlisted) doc page for `nextstrain`. Resolve the mismatch by using the standard Sphinx filesystem semantics in all our usage of the "doc" role and extend our rST to text conversion to explicitly handle the filesystem → URL semantic shift.
nextstrain · Jul 14, 2023 · 9c6332a · 9c6332a
1 parent e798a37
commit 9c6332a
Show file tree

Hide file tree

Showing 3 changed files with 10 additions and 3 deletions.
diff --git a/doc/commands/index.rst b/doc/commands/index.rst
@@ -24,7 +24,7 @@ run and visualize pathogen builds and access Nextstrain components like Augur
 and Auspice across computing platforms such as Docker, Conda, and AWS Batch.
 
 Run `nextstrain <command> --help` for usage information about each command.
-See <:doc:`/`> for more documentation.
+See <:doc:`/index`> for more documentation.
 
 optional arguments
 ==================

diff --git a/nextstrain/cli/__init__.py b/nextstrain/cli/__init__.py
@@ -6,7 +6,7 @@
 and Auspice across computing platforms such as Docker, Conda, and AWS Batch.
 
 Run `nextstrain <command> --help` for usage information about each command.
-See <:doc:`/`> for more documentation.
+See <:doc:`/index`> for more documentation.
 """
 
 

diff --git a/nextstrain/cli/rst/__init__.py b/nextstrain/cli/rst/__init__.py
@@ -22,6 +22,7 @@
 from docutils.parsers.rst.roles import register_local_role
 from docutils.utils import unescape                         # type: ignore
 from ..__version__ import __version__ as cli_version
+from ..util import remove_suffix
 from .sphinx import TextWriter
 
 
@@ -189,7 +190,13 @@ def doc_url(target: str) -> str:
         # Oh well.
         return target
 
-    return project_url.rstrip("/") + "/" + path.lstrip("/") + suffix
+    if path.endswith("/index"):
+        # a/b/index → a/b/ (e.g. implicitly a/b/index.html)
+        path_url = remove_suffix("index", path)
+    else:
+        path_url = path + (suffix or "")
+
+    return project_url.rstrip("/") + "/" + path_url.lstrip("/")
 
 
 class Reader(docutils.readers.standalone.Reader):