Merge pull request #91 from JWCook/ref_label_myst

ENH: Add MyST support and tests for ref labels

Author: JWCook

CHANGELOG.md

@@ -20,9 +20,18 @@
 
 - Added support for tagging Jupyter Notebooks using `nbsphinx` [gh-51](https://github.com/melissawm/sphinx-tags/pull/51)
 
-## Version 0.3.0
+## Version 0.3.0 (October 30, 2023)
 
 - Fixed tag labels with spaces
 - Fixed tag labels with emoji
 - Added normalization for tag URLs to remove/replace urlencoded characters
 - Exclude files that match `exclude_patterns` from being tagged
+
+## Version 0.3.1 (October 31, 2023)
+
+- Fixed doc links and minimum sphinx version
+
+## Unreleased
+
+- Added support for tags in directive body
+- Added ref label to tag pages, in the format `sphx_tag_<tagname>`

docs/quickstart.rst

@@ -42,33 +42,35 @@ Next, add the following configuration setting to ``conf.py``::
 
    tags_create_tags = True
 
-To assign one or more tags to a page in the documentation, use
+To assign one or more tags to a page in the documentation, use:
 
-.. code-block:: rst
+.. tab-set::
+
+    .. tab-item:: rST
+
+      .. code-block:: rst
+
+         .. tags:: tag1, tag2
+
+    .. tab-item:: MyST (Markdown)
+
+      .. code-block:: md
 
-   .. tags:: tag1, tag2
+         ```{tags} tag1, tag2
+         ```
 
 Tags must be separated by commas, and the tags will be shown in the rendered
-html output at the same position in the page as in the source .rst file.
+html output at the same position in the page as in the source file.
 
-For each tag, a new rst file is created in ``<output_dir>/<tagname>.rst``
+For each tag, a new source file is created in ``<output_dir>/<tagname>.<ext>``
 containing a table of contents of each file associated with that tag (see
-:ref:`config`). A reference label will be added to this rst file, to enable you to
+:ref:`config`). A reference label will be added to this file, to enable you to
 cross-reference to it. The reference label will have the format: ``sphx_tag_<tagname>``
 e.g., a reference would look like: ``:ref:`sphx_tag_tag1```.
 
 A :ref:`tagoverview` page is also created that can be added to the index and
 show all tags defined for this documentation set.
 
-.. note::
-
-   If you are using MyST to write your documentation in Markdown, you can use
-
-   ::
-
-      ```{tags} tag1, tag2
-      ```
-
 .. note::
 
    If you are using both ``md`` and ``rst`` files, all generated pages will be

pyproject.toml

@@ -21,7 +21,7 @@ dependencies = [
 
 [project.optional-dependencies]
 sphinx = [
-    "pydata-sphinx-theme",
+    "pydata-sphinx-theme>=0.13",
     "sphinx-design",
     "nbsphinx",
     "myst-parser"

src/sphinx_tags/__init__.py

@@ -172,10 +172,12 @@ def create_file(
         """
         # Get sorted file paths for tag pages, relative to /docs/_tags
         tag_page_paths = sorted([i.relpath(srcdir) for i in items])
+        ref_label = f"sphx_tag_{self.file_basename}"
 
         content = []
         if "md" in extension:
             filename = f"{self.file_basename}.md"
+            content.append(f"({ref_label})=")
             content.append(f"# {tags_page_title}: {self.name}")
             content.append("")
             content.append("```{toctree}")
@@ -189,11 +191,11 @@ def create_file(
         else:
             filename = f"{self.file_basename}.rst"
             header = f"{tags_page_title}: {self.name}"
+            content.append(f".. _{ref_label}:")
+            content.append("")
             content.append(header)
             content.append("#" * textwidth(header))
             content.append("")
-            #  Return link block at the start of the page"""
-            content.append(f".. _sphx_tag_{self.file_basename}:")
             content.append(".. toctree::")
             content.append("    :maxdepth: 1")
             content.append(f"    :caption: {tags_page_header}")

test/outputs/general/index.txt

@@ -52,3 +52,9 @@ Test document
   * {{🧪test tag; please ignore🧪}} (1)
 
     * Page 2
+
+
+Test ref
+========
+
+My tags: tag_1

test/sources/test-ipynb/index.rst

@@ -8,3 +8,7 @@ Test document
     page_5
     subdir/index
     _tags/tagsindex
+
+Test ref
+--------
+:ref:`sphx_tag_tag_1`

test/sources/test-myst/index.md

@@ -9,3 +9,6 @@ page_5
 subdir/index
 _tags/tagsindex
 ```
+
+## Test ref
+{ref}`sphx_tag_tag_1`

test/sources/test-rst/index.rst

@@ -9,3 +9,8 @@ Test document
    page_5
    subdir/index
    _tags/tagsindex
+
+Test ref
+--------
+
+:ref:`sphx_tag_tag_1`