8000 doc: allowing tags in body · melissawm/sphinx-tags@310c954 · GitHub
[go: up one dir, main page]
Skip to content

Commit 310c954

Browse files
story645story645
committed
doc: allowing tags in body
1 parent c4df648 commit 310c954

File tree

18 files changed

+126
-29
lines changed

18 files changed

+126
-29
lines changed

‎docs/configuration.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,3 +105,15 @@ Special characters
105105

106106
Tags can contain spaces and special characters such as emoji. In that case, the
107107
tag will be normalized when processed. See our :doc:`examples/examples` for more details.
108+
109+
Multiple lines of tags
110+
----------------------
111+
112+
Tags can be passed in either as arguments or in the body of the directive:
113+
114+
.. code-block:: rst
115+
116+
.. tags::
117+
118+
tag1, tag2, tag3,
119+
tag4, tag5, tag6,

‎src/sphinx_tags/__init__.py

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
from typing import List
99

1010
from docutils import nodes
11+
from sphinx.errors import ExtensionError
1112
from sphinx.util.docutils import SphinxDirective
1213
from sphinx.util.logging import getLogger
1314
from sphinx.util.matching import get_matching_files
@@ -28,16 +29,27 @@ class TagLinks(SphinxDirective):
2829
"""
2930

3031
# Sphinx directive class attributes
31-
required_arguments = 1
32+
required_arguments = 0
3233
optional_arguments = 200 # Arbitrary.
33-
has_content = False
34+
final_argument_whitespace = True
35+
has_content = True
3436

3537
# Custom attributes
3638
separator = ","
3739

3840
def run(self):
3941
# Undo splitting args by whitespace, and use our own separator (to support tags with spaces)
40-
tags = " ".join(self.arguments).split(self.separator)
42+
if not (self.arguments or self.content):
43+
raise ExtensionError("Tags must be passed in either as an argument or in the body of the tag.")
44+
45+
tags = []
46+
47+
if self.arguments:
48+
tags.extend((" ".join(self.arguments)).split(self.separator))
49+
50+
if self.content:
51+
tags.extend((" ".join(self.content)).split(self.separator))
52+
4153
tags = [t.strip() for t in tags]
4254

4355
tag_dir = Path(self.env.app.srcdir) / self.env.app.config.tags_output_dir

‎test/conftest.py

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,6 @@
1515

1616
import pytest
1717
import sphinx.testing
18-
import sphinx.testing.path
1918

2019
collect_ignore = ["sources", "outputs"]
2120
pytest_plugins = "sphinx.testing.fixtures"
@@ -31,11 +30,7 @@ def rootdir():
3130
resolved and copied as files.
3231
"""
3332

34-
def copytree(src, dest):
35-
shutil.copytree(src, dest, symlinks=True)
36-
37-
with patch.object(sphinx.testing.path.path, "copytree", copytree):
38-
yield sphinx.testing.path.path(SOURCE_ROOT_DIR)
33+
yield Path(SOURCE_ROOT_DIR)
3934

4035

4136
@pytest.fixture(scope="session", autouse=True)
@@ -44,9 +39,9 @@ def create_symlinks():
4439
symlink_dest_dir = SOURCE_ROOT_DIR / "test-symlink"
4540

4641
for file in SOURCE_ROOT_DIR.glob("test-rst/*.rst"):
47-
symlink(file, symlink_dest_dir / file.name)
42+
(symlink_dest_dir / file.name).symlink_to(file)
4843
for dir in SOURCE_ROOT_DIR.glob("test-rst/subdir*"):
49-
symlink(dir, symlink_dest_dir / dir.name, target_is_directory=True)
44+
(symlink_dest_dir / dir.name).symlink_to(dir, target_is_directory=True)
5045

5146
yield
5247

‎test/outputs/general/_tags/tag-3.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,5 @@ With this tag
88
* Page 1
99

1010
* Page 3
11+
12+
* Page 5

‎test/outputs/general/_tags/tag-4.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,5 @@ With this tag
66
^^^^^^^^^^^^^
77

88
* Page 1
9+
10+
* Page 5

‎test/outputs/general/_tags/tag2.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,5 @@ With this tag
66
^^^^^^^^^^^^^
77

88
* Page 1
9+
10+
* Page 5

‎test/outputs/general/_tags/tag_1.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,5 @@ With this tag
88
* Page 1
99

1010
* Page 2
11+
12+
* Page 5

‎test/outputs/general/_tags/tag_5.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,5 @@ With this tag
66
^^^^^^^^^^^^^
77

88
* Page 2
9+
10+
* Page 5

‎test/outputs/general/_tags/tagsindex.txt

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@ Tags overview
55
Tags
66
^^^^
77

8-
* [{(tag 4)}] (1)
8+
* [{(tag 4)}] (2)
99

10-
* tag 3 (2)
10+
* tag 3 (3)
1111

12-
* tag2 (1)
12+
* tag2 (2)
1313

14-
* tag_1 (2)
14+
* tag_1 (3)
1515

16-
* tag_5 (1)
16+
* tag_5 (2)
1717

1818
* {{🧪test tag; please ignore🧪}} (1)

‎test/outputs/general/index.txt

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,35 +7,47 @@ Test document
77

88
* Page 2
99

10+
* Page 5
11+
1012
* Subdir
1113

1214
* Page 3
1315

1416
* Tags overview
1517

16-
* [{(tag 4)}] (1)
18+
* [{(tag 4)}] (2)
1719

1820
* Page 1
1921

20-
* tag 3 (2)
22+
* Page 5
23+
24+
* tag 3 (3)
2125

2226
* Page 1
2327

2428
* Page 3
2529

26-
* tag2 (1)
30+
* Page 5
31+
32+
* tag2 (2)
2733

2834
* Page 1
2935

30-
* tag_1 (2)
36+
* Page 5
37+
38+
* tag_1 (3)
3139

3240
* Page 1
3341

3442
* Page 2
3543

36-
* tag_5 (1)
44+
* Page 5
45+
46+
* tag_5 (2)
3747

3848
* Page 2
49+
50+
* Page 5
3951

4052
* {{🧪test tag; please ignore🧪}} (1)
4153

0 commit comments

Comments
 (0)
0