feat: use versioned form of doc urls

This updates the links used for errors, but also for init templates.
clay-lake · Jul 12, 2024 · f0d7570 · f0d7570
1 parent 0cc6e70
commit f0d7570
Show file tree

Hide file tree

Showing 5 changed files with 23 additions and 17 deletions.
diff --git a/rockcraft/application.py b/rockcraft/application.py
@@ -34,7 +34,7 @@
     ProjectClass=project.Project,
     BuildPlannerClass=project.BuildPlanner,
     source_ignore_patterns=["*.rock"],
-    docs_url="https://documentation.ubuntu.com/rockcraft/en/stable",
+    docs_url="https://documentation.ubuntu.com/rockcraft/en/{version}",
 )
 
 

diff --git a/rockcraft/commands/init.py b/rockcraft/commands/init.py
@@ -68,7 +68,7 @@ class InitCommand(AppCommand):
             rockcraft_yaml=textwrap.dedent(
                 """\
                 name: {name}
-                # see https://documentation.ubuntu.com/rockcraft/en/stable/explanation/bases/
+                # see {versioned_url}/explanation/bases/
                 # for more information about bases and using 'bare' bases for chiselled rocks
                 base: [email protected] # the base environment for this rock
                 version: '0.1' # just for humans. Semantic versioning is recommended
@@ -91,7 +91,7 @@ class InitCommand(AppCommand):
             rockcraft_yaml=textwrap.dedent(
                 """\
                 name: {name}
-                # see https://documentation.ubuntu.com/rockcraft/en/stable/explanation/bases/
+                # see {versioned_url}/explanation/bases/
                 # for more information about bases and using 'bare' bases for chiselled rocks
                 base: [email protected] # the base environment for this Flask application
                 version: '0.1' # just for humans. Semantic versioning is recommended
@@ -107,7 +107,7 @@ class InitCommand(AppCommand):
                 # to ensure the flask-framework extension works properly, your Flask application
                 # should have an `app.py` file with an `app` object as the WSGI entrypoint.
                 # a `requirements.txt` file with at least the flask package should also exist.
-                # see https://documentation.ubuntu.com/rockcraft/en/stable/reference/extensions/flask-framework
+                # see {versioned_url}/reference/extensions/flask-framework
                 # for more information.
                 extensions:
                     - flask-framework
@@ -139,7 +139,7 @@ class InitCommand(AppCommand):
                 # you can add package slices or Debian packages to the image.
                 # package slices are subsets of Debian packages, which result
                 # in smaller and more secure images.
-                # see https://documentation.ubuntu.com/rockcraft/en/latest/explanation/chisel/
+                # see {versioned_url}/explanation/chisel/
 
                 # add this part if you want to add packages slices to your image.
                 # you can find a list of packages slices at https://github.com/canonical/chisel-releases
@@ -164,7 +164,7 @@ class InitCommand(AppCommand):
             rockcraft_yaml=textwrap.dedent(
                 """\
                 name: {name}
-                # see https://documentation.ubuntu.com/rockcraft/en/stable/explanation/bases/
+                # see {versioned_url}/explanation/bases/
                 # for more information about bases and using 'bare' bases for chiselled rocks
                 base: [email protected] # the base environment for this Django application
                 version: '0.1' # just for humans. Semantic versioning is recommended
@@ -246,17 +246,20 @@ def run(self, parsed_args: "argparse.Namespace") -> None:
         # Get the init profile
         init_profile = self._PROFILES[parsed_args.profile]
 
+        versioned_docs_url = self._app.versioned_docs_url
+
         # Setup the reference documentation link if available
         profile_reference_docs: str | None = None
-        if self._app.docs_url and init_profile.doc_slug:
-            profile_reference_docs = self._app.docs_url + init_profile.doc_slug
+        if versioned_docs_url and init_profile.doc_slug:
+            profile_reference_docs = versioned_docs_url + init_profile.doc_slug
 
         # Format the template, all templates should be tested to avoid risk of
         # expecting documentation when there isn't any set
         context = {
             "name": name,
             "snake_name": name.replace("-", "_").lower(),
             "profile_reference_docs": profile_reference_docs,
+            "versioned_url": versioned_docs_url,
         }
         rockcraft_yaml_path = init(init_profile.rockcraft_yaml.format(**context))
 

diff --git a/rockcraft/extensions/gunicorn.py b/rockcraft/extensions/gunicorn.py
@@ -240,7 +240,7 @@ def _app_prime(self):
             raise ExtensionError(
                 "flask-framework extension requires the 'prime' entry in the "
                 "flask-framework/install-app part to start with flask/app",
-                docs_url="https://documentation.ubuntu.com/rockcraft/en/stable/reference/extensions/flask-framework",
+                doc_slug="/reference/extensions/flask-framework",
                 logpath_report=False,
             )
         if not user_prime:
@@ -301,7 +301,7 @@ def check_project(self):
         if error_messages:
             raise ExtensionError(
                 "\n".join("- " + message for message in error_messages),
-                docs_url="https://documentation.ubuntu.com/rockcraft/en/stable/reference/extensions/flask-framework",
+                doc_slug="/reference/extensions/flask-framework",
                 logpath_report=False,
             )
 

diff --git a/tests/unit/test_cli.py b/tests/unit/test_cli.py
@@ -23,7 +23,7 @@
 import yaml
 from craft_cli import emit
 from rockcraft import cli, extensions, services
-from rockcraft.application import Rockcraft
+from rockcraft.application import Rockcraft, APP_METADATA
 from rockcraft.models import project
 
 
@@ -130,15 +130,17 @@ def test_run_init_flask(mocker, emitter, monkeypatch, new_dir, tmp_path):
 
     cli.run()
 
+    versioned_url = APP_METADATA.versioned_docs_url
+
     rockcraft_yaml_path = Path("rockcraft.yaml")
     rock_project_yaml = yaml.safe_load(rockcraft_yaml_path.read_text())
 
     assert len(rock_project_yaml["summary"]) < 80
     assert len(rock_project_yaml["description"].split()) < 100
     assert rockcraft_yaml_path.read_text() == textwrap.dedent(
-        """\
+        f"""\
             name: test-name
-            # see https://documentation.ubuntu.com/rockcraft/en/stable/explanation/bases/
+            # see {versioned_url}/explanation/bases/
             # for more information about bases and using 'bare' bases for chiselled rocks
             base: [email protected] # the base environment for this Flask application
             version: '0.1' # just for humans. Semantic versioning is recommended
@@ -154,7 +156,7 @@ def test_run_init_flask(mocker, emitter, monkeypatch, new_dir, tmp_path):
             # to ensure the flask-framework extension works properly, your Flask application
             # should have an `app.py` file with an `app` object as the WSGI entrypoint.
             # a `requirements.txt` file with at least the flask package should also exist.
-            # see https://documentation.ubuntu.com/rockcraft/en/stable/reference/extensions/flask-framework
+            # see {versioned_url}/reference/extensions/flask-framework
             # for more information.
             extensions:
                 - flask-framework
@@ -186,7 +188,7 @@ def test_run_init_flask(mocker, emitter, monkeypatch, new_dir, tmp_path):
             # you can add package slices or Debian packages to the image.
             # package slices are subsets of Debian packages, which result
             # in smaller and more secure images.
-            # see https://documentation.ubuntu.com/rockcraft/en/latest/explanation/chisel/
+            # see {versioned_url}/explanation/chisel/
 
             # add this part if you want to add packages slices to your image.
             # you can find a list of packages slices at https://github.com/canonical/chisel-releases
@@ -207,9 +209,9 @@ def test_run_init_flask(mocker, emitter, monkeypatch, new_dir, tmp_path):
     )
     emitter.assert_message(
         textwrap.dedent(
-            """\
+            f"""\
         Created 'rockcraft.yaml'.
-        Go to https://documentation.ubuntu.com/rockcraft/en/stable/reference/extensions/flask-framework to read more about the 'flask-framework' profile."""
+        Go to {versioned_url}/reference/extensions/flask-framework to read more about the 'flask-framework' profile."""
         )
     )
     monkeypatch.setenv("ROCKCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS", "0")

diff --git a/tools/schema/schema.py b/tools/schema/schema.py
@@ -39,6 +39,7 @@ def generate_project_schema() -> str:
     # Initialize the default template with a name
     context = {
         "name": "my-rock-name",
+        "versioned_url": "www.example.com",
     }
     # pylint: disable=W0212
     init_template = cli.commands.InitCommand._PROFILES[