fix: remove references to recently archived site

CHANGELOG.md

@@ -2,11 +2,17 @@
 
 ## Upcoming
 
+* Removes or replaces docs use of archived example product documentation site.
 * Remove scripts and references to unused HTML metrics.
 * Pin myst-parser package version to 4.0 to avoid conflicts.
 
 ### Changed
 
+* `docs/conf.py` [#502](https://github.com/canonical/sphinx-docs-starter-pack/pull/502)
+* `docs/how-to/guidance.rst` [#502](https://github.com/canonical/sphinx-docs-starter-pack/pull/502)
+* `docs/reference/index.rst` [#502](https://github.com/canonical/sphinx-docs-starter-pack/pull/502)
+* `docs/reference/myst-syntax-reference.md` [#502](https://github.com/canonical/sphinx-docs-starter-pack/pull/502)
+* `docs/reference/rst-syntax-reference.rst` [#502](https://github.com/canonical/sphinx-docs-starter-pack/pull/502)
 * `docs/requirements.txt` [#496](https://github.com/canonical/sphinx-docs-starter-pack/pull/496)
 * `docs/Makefile` [#490](https://github.com/canonical/sphinx-docs-starter-pack/pull/490)
 * `docs/.sphinx/update_sp.py` [#490](https://github.com/canonical/sphinx-docs-starter-pack/pull/490)

docs/conf.py

@@ -366,8 +366,7 @@
         myst_substitutions = yaml.safe_load(fd.read())
 
 # Add configuration for intersphinx mapping
-
+# Map only the Sphinx documentation sets that you need to link to from your docs set.
 intersphinx_mapping = {
-    'starter-pack': ('https://canonical-example-product-documentation.readthedocs-hosted.com/en/latest', None),
     'sphinxcontrib-mermaid': ('https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest', None)
 }

docs/how-to/guidance.rst

@@ -21,8 +21,3 @@ Other resources
 ---------------
 
 Canonical documentation uses `Diátaxis`_.
-
-The following documentation repository contains an example for how to implement this structure:
-
-- `Example product documentation <https://canonical-example-product-documentation.readthedocs-hosted.com/>`_
-- `Example product documentation repository <https://github.com/canonical/example-product-documentation>`_

docs/reference/index.rst

@@ -5,7 +5,6 @@ These documents provide an overview of different features of the starter pack.
 
 Also see the following information:
 
-- `Example product documentation`_ and `Example product documentation repository`_
 - `Sphinx documentation starter pack repository`_
 
 Contents

docs/reference/myst-syntax-reference.md

@@ -345,30 +345,25 @@ You can add targets at any place in the documentation. However, if there is no h
 
 ```{list-table}
    :header-rows: 1
+   :widths: 7 3 3
 
 * - Input
   - Output
-  - Output on GitHub
   - Description
 * - `(target_ID)=`
   -
-  - \(target_ID\)=
   - Adds the target ``target_ID``.
 * - `` {ref}`a_section_target_myst` ``
   - {ref}`a_section_target_myst`
-  - \{ref\}`a_section_target_myst`
   - References a target that has a title.
 * - `` {ref}`link text <a_random_target_myst>` ``
   - {ref}`link text <a_random_target_myst>`
-  - \{ref\}`link text <a_random_target_myst>`
   - References a target and specifies a title.
-* - `` {ref}`starter-pack:home` ``
-  - {ref}`starter-pack:home`
-  - \{ref\}`starter-pack:home`
-  - You can also reference targets in other doc sets.
+* - `` {ref}`project_key:an_external_target` ``
+  - Default link text
+  - You can also reference targets in other Sphinx projects. `project-key` must be a key in the `intersphinx_mapping` dictionary in `conf.py`. The link text defaults to the target's title.
 * - ``[`xyz`](a_random_target_myst)``
   - [`xyz`](a_random_target_myst)
-  - [`xyz`](a_random_target_myst) (link is broken)
   - Use Markdown syntax if you need markup on the link text.
 ```
 
@@ -388,25 +383,19 @@ Use MyST syntax to automatically extract the link text. When overriding the link
 
 * - Input
   - Output
-  - Output on GitHub
   - Status
 * - `` {doc}`index` ``
   - {doc}`index`
-  - {doc}<span></span>`index`
   - Preferred.
 * - `[](index)`
   - [](index)
-  -
   - Do not use.
 * - `[Index page](index)`
-  - [Index page](index)
   - [Index page](index)
   - Preferred when overriding the link text.
 * - `` {doc}`Index page <index>` ``
   - {doc}`Index page <index>`
-  - {doc}<span></span>`Index page <index>`
   - Alternative when overriding the link text.
-
 ```
 
 Adhere to the following conventions:

docs/reference/rst-syntax-reference.rst

@@ -419,12 +419,12 @@ You can add targets at any place in the documentation. However, if there is no h
    * - ``:ref:`a_section_target```
      - :ref:`a_section_target`
      - References a target that has a title.
-   * - ``:ref:`Link text <a_random_target>```
-     - :ref:`Link text <a_random_target>`
+   * - ``:ref:`Provided link text <a_random_target>```
+     - :ref:`Provided link text <a_random_target>`
      - References a target and specifies a title.
-   * - ``:ref:`starter-pack:home```
-     - :ref:`starter-pack:home`
-     - You can also reference targets in other doc sets.
+   * - ``:external+project_key:ref:`an_external_target```
+     - Default link text
+     - You can also reference targets in other Sphinx projects. ``project-key`` must be a key in the ``intersphinx_mapping`` dictionary in ``conf.py``. The link text defaults to the target's title.
 
 Adhere to the following conventions:
 
@@ -439,23 +439,25 @@ If a documentation page does not have a target, you can still reference it by us
 
 .. list-table::
    :header-rows: 1
+   :widths: 8 2
 
    * - Input
      - Output
    * - ``:doc:`index```
      - :doc:`index`
-   * - ``:doc:`Link text <index>```
-     - :doc:`Link text <index>`
-   * - ``:doc:`starter-pack:how-to/index```
-     - :doc:`starter-pack:how-to/index`
-   * - ``:doc:`Link text <starter-pack:how-to/index>```
-     - :doc:`Link text <starter-pack:how-to/index>`
+   * - ``:doc:`Provided link text <index>```
+     - :doc:`Provided link text <index>`
+   * - ``:external+project_key:doc:`howto/index```
+     - Default link text (from document title)
+   * - ``:external+project_key:doc:`Provided link text <how-to/index>```
+     - Provided link text
 
 Adhere to the following conventions:
 
 - Only use the ``:doc:`` role when you cannot use the ``:ref:`` role, thus only if there is no target at the top of the file and you cannot add it. When using the ``:doc:`` role, your reference will break when a file is renamed or moved.
 - Override the link text only when it is necessary. If you can use the document title as link text, do so, because the text will then update automatically if the title changes.
 - Never "override" the link text with the same text that would be generated automatically.
+- When using an external target, ``project_key`` must be a key in the ``intersphinx_mapping`` dictionary in ``conf.py``.
 
 Navigation
 ----------